feat: general vector matching improvements

Release-As: 0.0.19

Author: adhityaravi

src/theow/_core/_chroma_store.py

@@ -180,7 +180,12 @@ def query_rules(
         """
         coll = self._get_collection(collection)
 
-        where = metadata_filter if metadata_filter else None
+        if metadata_filter and len(metadata_filter) > 1:
+            where = {"$and": [{k: v} for k, v in metadata_filter.items()]}
+        elif metadata_filter:
+            where = metadata_filter
+        else:
+            where = None
 
         try:
             results = coll.query(

src/theow/_core/_explorer.py

@@ -21,8 +21,10 @@
     ExplorationSignal,
     GiveUp,
     RequestTemplates,
+    RuleResolved,
     SubmitRule,
     _escalate,
+    make_augmentation_tools,
     make_direct_fix_tools,
     make_ephemeral_tools,
     make_search_tools,
@@ -70,6 +72,7 @@ def __init__(
         self._pending_cleanup: list[Path] = []  # Files to clean up after all retries
         self._last_give_up_reason: str | None = None
         self._last_done_message: str | None = None
+        self._escalate_next: bool = False
 
     def set_gateway(self, gateway: LLMGateway) -> None:
         """Set the LLM gateway (for lazy initialization)."""
@@ -223,7 +226,15 @@ def _run_conversation(
         search_tools = make_search_tools(self._chroma, collection, self._rules_dir)
         ephemeral_tools = make_ephemeral_tools(self._rules_dir)
         validation_tools = make_validation_tools(self._rules_dir, context, self._action_registry)
-        all_tools = signal_tools + search_tools + ephemeral_tools + validation_tools + tools
+        augmentation_tools = make_augmentation_tools(self._rules_dir, context, self._chroma)
+        all_tools = (
+            signal_tools
+            + search_tools
+            + ephemeral_tools
+            + validation_tools
+            + augmentation_tools
+            + tools
+        )
         if allow_escalation and self._secondary_gateway is not None:
             all_tools.append(_escalate)
 
@@ -251,14 +262,22 @@ def _run_conversation(
         for gw in self._gateways:
             gw.set_gateway_config({"rules_dir": self._rules_dir})
 
-        signal = self._converse(messages, all_tools)
+        if allow_escalation and self._escalate_next and self._secondary_gateway is not None:
+            self._escalate_next = False
+            logger.info("Escalating to secondary model after action failure")
+            signal = self._converse_on(
+                self._secondary_gateway, messages, all_tools, self._default_budget
+            )
+        else:
+            signal = self._converse(messages, all_tools)
         result = self._handle_signal(
             signal,
             messages,
             all_tools,
             context,
             collection,
             allow_escalation=allow_escalation,
+            hint=hint,
         )
 
         # Reset gateway state after conversation ends
@@ -328,6 +347,7 @@ def _handle_signal(
         context: dict[str, Any],
         collection: str,
         allow_escalation: bool = False,
+        hint: str | None = None,
     ) -> tuple[Rule | None, bool]:
         """Handle exploration signal with pattern matching.
 
@@ -350,6 +370,15 @@ def _handle_signal(
                 logger.warning("Exploration unsuccessful", reason=reason)
                 return None, True
 
+            case RuleResolved(summary=summary):
+                logger.info("Explorer augmented existing rule", summary=summary)
+                # Re-check chroma — augmentation should have made an existing rule findable
+                chroma_match = self._check_chroma(context, collection)
+                if chroma_match:
+                    return chroma_match, True
+                logger.warning("Rule resolved signal but no chroma match found")
+                return None, True
+
             case Escalate(findings=findings):
                 if self._secondary_gateway is None:
                     logger.warning("Escalation requested but no secondary gateway")
@@ -370,6 +399,7 @@ def _handle_signal(
                     context,
                     collection,
                     allow_escalation=False,
+                    hint=hint,
                 )
 
             case RequestTemplates():
@@ -378,6 +408,16 @@ def _handle_signal(
                     rules_dir=self._rules_dir,
                     actions_dir=self._rules_dir.parent / "actions",
                 )
+                templates += (
+                    "\n\n## CRITICAL: Action Design"
+                    "\n\nActions MUST do ONE atomic fix and return ok."
+                    " Do NOT run verification or rebuild commands inside the action."
+                    " The recovery loop handles verification, retries, and iteration."
+                    " Actions that verify internally will fail on unrelated errors"
+                    " and get rejected even when their fix was correct."
+                )
+                if hint:
+                    templates += f"\n\n## Caller Constraints (MUST follow)\n\n{hint}"
                 messages.append({"role": "user", "content": templates})
                 signal = self._converse(messages, tools)
                 return self._handle_signal(
@@ -387,6 +427,7 @@ def _handle_signal(
                     context,
                     collection,
                     allow_escalation=allow_escalation,
+                    hint=hint,
                 )
 
             case SubmitRule(rule_file=rule_file, action_file=action_file):
@@ -413,6 +454,7 @@ def _handle_signal(
                         context,
                         collection,
                         allow_escalation=False,
+                        hint=hint,
                     )
                 return rule, True
 
@@ -673,6 +715,19 @@ def run_direct(
         self._last_give_up_reason = None
         self._last_done_message = None
 
+        if self._session_count >= self._session_limit:
+            logger.warning(
+                "Session limit reached", count=self._session_count, limit=self._session_limit
+            )
+            return False
+
+        self._session_count += 1
+
+        logger.info(
+            "Starting LLM action",
+            session=f"{self._session_count}/{self._session_limit}",
+        )
+
         can_escalate = allow_escalation and self._secondary_gateway is not None
         caller_tools = make_direct_fix_tools(self._rules_dir) + tools
 

src/theow/_core/_models.py

@@ -312,6 +312,23 @@ def act(self) -> list[Any]:
 
         return results
 
+    def add_fact(self, fact: Fact) -> None:
+        """Append a new fact to the rule's when block and persist to disk."""
+        self.when.append(fact)
+        if self._source_path:
+            self.to_yaml(self._source_path)
+
+    def add_example_to_fact(self, fact_key: str, example: str) -> bool:
+        """Append an example to an existing fact. Returns True if found and added."""
+        for fact in self.when:
+            if fact.fact == fact_key and fact.regex is not None:
+                if example not in fact.examples:
+                    fact.examples.append(example)
+                    if self._source_path:
+                        self.to_yaml(self._source_path)
+                    return True
+        return False
+
     def content_hash(self) -> str:
         """Compute hash of rule content for change detection."""
         content = self.to_yaml()

src/theow/_core/_prompts.py

@@ -45,13 +45,29 @@
 3. **Search first** - Use `_search_rules()` and `_search_actions()` to check if a
    similar solution already exists. Don't reinvent the wheel.
 
-4. **Investigate** - Read files, run commands, understand the root cause.
+4. **Augment before creating** - If an existing rule handles a similar problem but
+   its facts don't quite match, use `_add_fact_to_rule()` to extend its matching,
+   or `_add_example_to_rule()` to improve its search recall. This is ALWAYS preferred
+   over creating a duplicate rule. Only create a new rule when no existing rule
+   covers the same problem domain.
 
-5. **Fix & verify** - Apply a fix and confirm it works.
+   **IMPORTANT**: `_add_example_to_rule()` only improves vector search recall — it
+   does NOT change fact matching. If the rule's `when` facts don't match the current
+   error, you MUST also use `_add_fact_to_rule()` to extend its matchers.
 
-6. **Codify** - When ready to write a rule, call `request_templates()` to get
+   After augmenting, ALWAYS call `_test_rule_match(rule_path)` to verify the rule
+   now matches the current error context. Only call `_rule_resolved(summary)` after
+   `_test_rule_match` confirms all facts pass. The system will re-check rules and
+   execute the matching one.
+
+5. **Investigate** - Read files, run commands, understand the root cause.
+
+6. **Fix & verify** - Apply a fix and confirm it works.
+
+7. **Codify** - When ready to write a rule, call `request_templates()` to get
    the rule/action syntax. Then write the files and call `submit_rule()`.
 
+If augmenting existing rules resolves the issue, verify with `_test_rule_match()` then call `_rule_resolved(summary)`.
 If the problem can't or shouldn't be automated, call `_give_up(reason)`.
 """
 
@@ -63,9 +79,28 @@
 Investigate this failure. Start by searching for existing rules that might handle similar errors.
 """
 
-TEMPLATES = """## Rule & Action Templates
+TEMPLATES = """## Before Creating a New Rule
+
+STOP. Are you sure a new rule is necessary?
+
+Vector search may have missed an existing rule because:
+- The rule's examples don't cover this specific error wording
+- The rule's description uses different terminology
+- The error context was too noisy for similarity matching
+
+Before writing a new rule:
+1. Re-check the rules you found with `_search_rules()` — could any of them
+   handle this case if their facts were extended?
+2. If yes, use `_add_fact_to_rule()` to extend matching or
+   `_add_example_to_rule()` to improve search recall. This is preferred.
+3. Only create a new rule if the error pattern is genuinely novel and no
+   existing rule covers the same problem domain.
+
+If you are certain a new rule is needed, proceed below.
+
+## Rule & Action Templates
 
-Now write a rule that captures the GENERAL pattern (not just this specific case).
+Write a rule that captures the GENERAL pattern (not just this specific case).
 
 ### CRITICAL: Verify Before Writing
 
@@ -138,6 +173,10 @@ def action_name(workspace: str, expected: str) -> dict:
 - The `@action("name")` decorator MUST include the name string. Bare `@action` will silently fail.
 - Keep actions succinct and readable. Compose long functions into smaller helpers.
 - Solve the problem generically. NEVER hardcode case-specific values.
+- **Do ONE atomic fix and return `{{"status": "ok"}}`**. Do NOT run verification or
+  rebuild commands inside the action — the recovery loop handles verification, retries,
+  and iteration. Actions that verify internally will fail on unrelated errors and get
+  rejected even when their fix was correct.
 
 **Workflow:**
 1. `_write_rule(name, content)` → returns path in result

src/theow/_core/_recover.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import os
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Callable, Generic, TypeVar
@@ -66,8 +67,27 @@ def __init__(
         self._retry = 0
         self._attempt_num = 0
         self._explored = False
+        self._seen_errors: set[str] = set()
         self.abort = False
 
+    def check_cycle(self, context: dict[str, Any]) -> bool:
+        """Check if this error context has been seen before (cycle detection).
+
+        Returns True if context fingerprint was already seen (cycle).
+        Otherwise records it and returns False.
+        """
+        fp = self._error_fingerprint(context)
+        if fp in self._seen_errors:
+            return True
+        self._seen_errors.add(fp)
+        return False
+
+    @staticmethod
+    def _error_fingerprint(context: dict[str, Any]) -> str:
+        """Create a hash fingerprint of error context for cycle detection."""
+        raw = str(sorted((k, str(v)[:500]) for k, v in context.items()))
+        return hashlib.sha256(raw.encode()).hexdigest()
+
     @property
     def max_iterations(self) -> int:
         extra = self._config.max_depth if self._config.explorable else 0
@@ -148,6 +168,8 @@ def replay_explored_rule(self, rule: Rule, context: dict[str, Any]) -> bool:
 
         self._engine._chroma.update_rule_stats(self._config.collection, rule.name, False)
         gave_up = self._engine._explorer._last_give_up_reason
+        if not gave_up and self._try_escalate_action_failure(rule, context):
+            return True
         _teardown_failure(
             self._engine,
             self._hook_state,
@@ -258,6 +280,22 @@ def try_escalate_unverified(self, rule: Rule, context: dict[str, Any]) -> bool:
         )
         return self._engine.execute_rule(rule, context, escalation_context=findings)
 
+    def _try_escalate_action_failure(self, rule: Rule, context: dict[str, Any]) -> bool:
+        """Flag explorer to use secondary gateway on next exploration.
+
+        When an explored rule's action fails, the recovery loop already retries
+        with a new exploration.  This just ensures that next exploration uses
+        the secondary (escalated) model instead of the primary.
+        """
+        if not self._config.allow_escalation:
+            return False
+        if self._engine._explorer._secondary_gateway is None:
+            return False
+
+        logger.info("Escalating after action failure", rule=rule.name)
+        self._engine._explorer._escalate_next = True
+        return False
+
     def cleanup(self) -> None:
         _cleanup(self._engine, self._rejected)
 
@@ -300,6 +338,7 @@ def recover(
 
     logger.info("Failure captured", error=_truncate(attempt.context.get("stderr", "")))
     loop = _RecoveryLoop(engine, config, before_attempt, after_attempt)
+    loop.check_cycle(attempt.context)  # seed with initial error
 
     try:
         for _ in range(loop.max_iterations):
@@ -335,6 +374,13 @@ def recover(
             # captures (fixed one instance, another instance of same pattern).
             new_captures = rule.matches(attempt.context)
             if new_captures is None or new_captures != prev_captures:
+                if loop.check_cycle(attempt.context):
+                    logger.warning(
+                        "Recovery cycle detected",
+                        rule=rule.name,
+                        depth=loop._depth,
+                    )
+                    break
                 if not loop.on_progress(rule):
                     break
                 continue