openreflex 0.5.2__tar.gz → 0.5.3__tar.gz

{openreflex-0.5.2/src/openreflex.egg-info → openreflex-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openreflex
-Version: 0.5.2
+Version: 0.5.3
 Summary: Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live
 Author: vishnu-77
 License-Expression: MIT

{openreflex-0.5.2 → openreflex-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openreflex"
-version = "0.5.2"
+version = "0.5.3"
 description = "Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live"
 readme = "README.md"
 license = "MIT"

{openreflex-0.5.2 → openreflex-0.5.3}/src/openreflex/__init__.py

@@ -1,3 +1,3 @@
 """Ambient, local execution intelligence."""
 
-__version__ = "0.5.2"
+__version__ = "0.5.3"

{openreflex-0.5.2 → openreflex-0.5.3}/src/openreflex/decision.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from dataclasses import asdict, dataclass, field
 from typing import Iterable
 
-from .models import CandidatePath, Experience
+from .models import CandidatePath, Execution, Experience, Task
 from .policy import Policy
 
 
@@ -233,3 +233,31 @@ def render_trace(snapshots: list[DecisionSnapshot]) -> str:
             detail += f" · {snapshot.event}"
         lines.append(f"{minute:02d}:{second:02d} {label:<9} {detail}")
     return "\n".join(lines)
+
+
+def render_paths(execution: Execution, task: Task, paths: list[CandidatePath]) -> str:
+    best = min(paths, key=lambda p: (p.dominated_by is not None, not p.within_limits, -p.score))
+    chosen = next((p for p in paths if p.id == execution.chosen_path_id), None)
+    recommended = next((p for p in paths if p.id == execution.recommended_path_id), None)
+    lines = ["OPENREFLEX / PATHS", "",
+             f"Task           {task.task_class} - {task.description}",
+             f"Recommended    {recommended.strategy if recommended else 'n/a'}"]
+    if chosen is not None:
+        lines.append(f"Followed       {chosen.strategy} "
+                      f"({'inferred from tool calls' if execution.chosen_inferred else 'explicit'})")
+    else:
+        lines.append("Followed       not yet determined" +
+                      (" (execution still running)" if execution.ended_at is None
+                       else " (no strategy could be inferred from tool-call evidence)"))
+    lines += ["", "CANDIDATES"]
+    for path in paths:
+        tags = ", ".join(tag for tag in (("recommended" if path is recommended else None),
+                                          ("followed" if path is chosen else None)) if tag)
+        note = (f"dominated by {path.dominated_by}" if path.dominated_by else
+                "over your limit" if not path.within_limits else
+                (f"{path.score:+.2f} vs {best.score:+.2f}" if path is not best else ""))
+        suffix = " ".join(part for part in (f"[{tags}]" if tags else "", f"({note})" if note else "") if part)
+        lines.append(f"  {path.strategy:<14} score {path.score:+.2f}  success {path.success_probability:.0%}  "
+                      f"~{path.tool_calls:.0f} calls  ~{path.time_seconds / 60:.0f} min  risk {path.risk:.2f} "
+                      f"{suffix}".rstrip())
+    return "\n".join(lines)

{openreflex-0.5.2 → openreflex-0.5.3}/src/openreflex/engine.py

@@ -7,7 +7,7 @@ from collections import Counter
 from pathlib import Path
 
 from . import control, detect, learning
-from .decision import DecisionSnapshot, make_snapshot, render_recap, render_trace, render_why
+from .decision import DecisionSnapshot, make_snapshot, render_paths, render_recap, render_trace, render_why
 from .models import CandidatePath, Context, Execution, Experience, Lesson, Outcome, Status, Task, ToolCall, uid
 from .policy import load_policy
 from .privacy import PROGRESS, categorize, error_signature, file_paths, fingerprint, redact
@@ -293,6 +293,24 @@ class Engine:
     def trace(self, execution_id: str | None = None) -> str:
         return render_trace(self.decision_snapshots(execution_id))
 
+    def candidate_paths(self, execution_id: str | None = None) -> tuple[Execution, Task, list[CandidatePath]] | None:
+        execution = self.store.get(execution_id) if execution_id else self.current_execution()
+        if execution is None:
+            return None
+        task = self._task(execution)
+        paths = self.store.list("CandidatePath", "task_id", task.id)
+        paths.sort(key=lambda p: (p.dominated_by is not None, not p.within_limits, -p.score, p.strategy))
+        return execution, task, paths
+
+    def paths(self, execution_id: str | None = None) -> str:
+        found = self.candidate_paths(execution_id)
+        if found is None:
+            return "OPENREFLEX / PATHS\n\nNo execution recorded yet."
+        execution, task, paths = found
+        if not paths:
+            return "OPENREFLEX / PATHS\n\nNo candidate paths recorded for the current task."
+        return render_paths(execution, task, paths)
+
     def retrieve(self, description: str, task_class: str | None = None,
                  k: int | None = None) -> list[tuple[Experience, float]]:
         query = embed(description)
@@ -684,7 +702,7 @@ def render_context(task: Task, paths: list[CandidatePath], retrieved: list[tuple
     if shown:
         lines.append("Lessons:")
         lines += [f"- {lesson.text}" + (f" (seen {support}x)" if support > 1 else "") for lesson, _, support in shown]
-    lines.append("Advisory only. If you follow a different approach, the choose_path tool records it.")
+    lines.append("Advisory; choose_path records deviations.")
     text = "\n".join(lines)
     max_chars = cfg.integer("context.max_chars")
     return text if len(text) <= max_chars else text[: max_chars - 1] + "..."

{openreflex-0.5.2 → openreflex-0.5.3}/src/openreflex/entrypoint.py

@@ -164,12 +164,18 @@ def _prompt_state(project: Path, output: str, project_context: str | None) -> No
     match = re.search(r"Suggested path:\s*([a-z0-9_-]+)", text, re.I)
     if match:
         route = match.group(1)
+    alternatives = None
+    match = re.search(r"Alternatives:\s*(.+)", text)
+    if match:
+        alternatives = match.group(1).strip()
     match = re.search(r"\[OpenReflex\]\s+(BUILD|INVESTIGATE|THINK)", text, re.I)
     if match:
         mode = match.group(1).lower()
     task = {"active": True, "mode": mode}
     if route:
         task["route"] = route
+    if alternatives:
+        task["alternatives"] = alternatives
     # A new prompt is a new task surface. Do not carry the previous task's call count/activity into it.
     phase = "recall" if experiences or project_context else ("investigate" if mode == "investigate" else
                                                               "think" if mode == "think" else "watch")
@@ -245,9 +251,11 @@ def _stop_state(project: Path, agent: str, session: str, output: str, payload: d
     outcome = "execution captured"
     data = _output_dict(output)
     notice = str(data.get("systemMessage") or "") if isinstance(data, dict) else ""
-    match = re.search(r"(?:COMPLETE|FAILED|UNVERIFIED|FINISHED)\s*\n\s*([^\s·]+)", notice)
+    match = re.search(r"(?:COMPLETE|FAILED|UNVERIFIED|FINISHED)\s*\n\s*([^\s·]+)(?:\s*·\s*([a-z0-9_-]+))?", notice)
     if match:
         outcome = match.group(1)
+        if match.group(2):
+            task["followed"] = match.group(2)
     reinforce_latest_execution(project, agent, session)
     task["active"] = False
     update_state(project, "remember", outcome=outcome, execution={}, task=task, activity={})

{openreflex-0.5.2 → openreflex-0.5.3}/src/openreflex/mcp_server.py

@@ -179,6 +179,22 @@ def build_server(project: Path) -> FastMCP:
         project is approved."""
         return run(lambda e: e.trace())
 
+    @tool("Get candidate paths", READ)
+    def get_candidate_paths() -> str:
+        """Show every candidate path OpenReflex considered for the most recent task side by side.
+        Returns: plain text with each strategy's score, success probability, cost/risk numbers, and whether it
+        was dominated; which path was recommended; and which one was actually followed - explicit (via
+        choose_path), inferred from tool-call evidence, or not yet determined while the execution is still
+        running.
+        Use when: the user asks what other approaches were considered, or whether the agent followed the
+        suggested path.
+        Not for: a single recommendation's reasoning (use explain_decision) or the decision timeline (use
+        get_execution_trace).
+        Side effects: none; read-only.
+        Errors: 'No execution recorded yet' before any task was planned; a 'not enabled' message until the
+        project is approved."""
+        return run(lambda e: e.paths())
+
     @tool("Get Reflex Score", READ)
     def get_reflex_score() -> ReflexScoreResult:
         """Return the latest decision's Reflex Score and machine-readable components.

{openreflex-0.5.2 → openreflex-0.5.3}/src/openreflex/reflex_index.py

@@ -13,6 +13,7 @@ import math
 import os
 import re
 import time
+from collections import Counter
 from pathlib import Path
 
 from .engine import Engine
@@ -43,6 +44,9 @@ def _terms(text: str) -> set[str]:
     stop = {
         "this", "that", "with", "from", "into", "when", "where", "what", "fix", "add", "make", "please",
         "project", "issue", "bug", "code", "change", "update", "implement", "create",
+        "how", "why", "who", "which", "any", "all", "some", "without", "within",
+        "the", "and", "for", "are", "was", "were", "has", "have", "had", "not", "but",
+        "used", "use", "using", "uses", "need", "needs", "file", "files",
     }
     # Split camelCase before lowercasing, then split path/identifier punctuation. This
     # makes `charts/payments/values.yaml`, `validate_expired_token` and
@@ -57,9 +61,24 @@ def _terms(text: str) -> set[str]:
         terms.add(token)
         if len(token) > 4 and token.endswith("s"):
             terms.add(token[:-1])
+        stem = _stem(token)
+        if stem:
+            terms.add(stem)
     return terms
 
 
+def _stem(token: str) -> str | None:
+    """Strip a gerund "-ing" suffix so e.g. "wrapping" also matches a symbol named `wrap_text`.
+    Added as an extra term alongside the original (never replacing it), same as the plural-`s` handling
+    above, so a wrong guess only adds a low-value extra term rather than losing a real match."""
+    if len(token) > 6 and token.endswith("ing"):
+        stem = token[:-3]
+        if len(stem) >= 4 and stem[-1] == stem[-2] and stem[-1] not in "aeiou":
+            stem = stem[:-1]
+        return stem
+    return None
+
+
 def _evidence_state(item: dict) -> str:
     verified = int(item.get("verified_successes", 0))
     observations = int(item.get("observations", 0))
@@ -200,11 +219,23 @@ def account_project_context(project: Path, agent: str, session: str, context: st
         engine.close()
 
 
-def _file_score(item: dict, query: set[str]) -> float:
+def _term_idf(indexed: list[dict]) -> dict[str, float]:
+    """Smoothed IDF so a match on a rare term (`shell_completion`) outweighs a match on a
+    term shared by dozens of files (`test`, `type`) - otherwise a test file with many
+    generically-named symbols can out-score the one source file that actually matters."""
+    doc_count = len(indexed) or 1
+    frequency: Counter[str] = Counter()
+    for item in indexed:
+        terms = _terms(str(item.get("path", ""))) | _terms(" ".join(str(s) for s in item.get("symbols", [])))
+        frequency.update(terms)
+    return {term: math.log((doc_count + 1) / (count + 1)) + 1.0 for term, count in frequency.items()}
+
+
+def _file_score(item: dict, query: set[str], idf: dict[str, float]) -> float:
     path_terms = _terms(str(item.get("path", "")))
     symbol_terms = _terms(" ".join(str(symbol) for symbol in item.get("symbols", [])))
-    path_overlap = len(query & path_terms)
-    symbol_overlap = len(query & symbol_terms)
+    path_weight = sum(idf.get(term, 1.0) for term in query & path_terms)
+    symbol_weight = sum(idf.get(term, 1.0) for term in query & symbol_terms)
     empirical = (
         4.0 * int(item.get("verified_successes", 0))
         + 1.5 * int(item.get("successful_outcomes", 0))
@@ -213,8 +244,8 @@ def _file_score(item: dict, query: set[str]) -> float:
     )
     hotspot = min(3.0, math.log1p(max(0, int(item.get("hotspot", 0)))) * 0.9)
     return (
-        path_overlap * 10.0
-        + symbol_overlap * 7.0
+        path_weight * 10.0
+        + symbol_weight * 7.0
         + ROLE_BONUS.get(str(item.get("role")), 0.0)
         + hotspot
         + min(empirical, 12.0)
@@ -250,7 +281,8 @@ def context_for_task(project: Path, description: str, *, max_files: int = 6, max
     query = _terms(description)
     indexed = [item for item in snapshot.get("indexed_files", []) if item.get("path")]
     by_path = {str(item["path"]): item for item in indexed}
-    scored = [(_file_score(item, query), item) for item in indexed]
+    idf = _term_idf(indexed)
+    scored = [(_file_score(item, query, idf), item) for item in indexed]
     scored = [(score, item) for score, item in scored if score > 0]
 
     base_limit = max(1, max_files - 1)
@@ -280,8 +312,8 @@ def context_for_task(project: Path, description: str, *, max_files: int = 6, max
     if selected:
         lines.append("Likely project locations: " + ", ".join(str(item["path"]) for item in selected) + ".")
         symbol_parts = []
-        for item in selected[:4]:
-            symbols = [str(symbol) for symbol in item.get("symbols", [])[:3]]
+        for item in selected[:2]:
+            symbols = [str(symbol) for symbol in item.get("symbols", [])[:2]]
             if symbols:
                 symbol_parts.append(f"{item['path']} -> {', '.join(symbols)}")
         if symbol_parts:
@@ -299,6 +331,5 @@ def context_for_task(project: Path, description: str, *, max_files: int = 6, max
         lines.append(
             f"Execution support: selected locations include {supported} explicit verified-success observation(s)."
         )
-    lines.append("Evidence: project-map and Git signals are structural priors; execution outcome evidence is counted separately.")
     text = "\n".join(lines)
     return text if len(text) <= 1800 else text[:1797] + "..."

{openreflex-0.5.2 → openreflex-0.5.3}/src/openreflex/tui.py

@@ -222,6 +222,8 @@ def dashboard(project: Path, *, colour: bool | None = None) -> str:
               f"  phase            {phase.upper()}",
               f"  mode             {str(task.get('mode') or 'build').upper()}",
               f"  suggested path   {task.get('route') or '-'}",
+              f"  alternatives     {task.get('alternatives') or '-'}",
+              f"  followed         {task.get('followed') or '-'}",
               f"  recall           {recall.get('experiences', 0)} related",
               f"  activity         {activity or '-'}",
               f"  calls            {execution.get('calls', 0)}",

{openreflex-0.5.2 → openreflex-0.5.3/src/openreflex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openreflex
-Version: 0.5.2
+Version: 0.5.3
 Summary: Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live
 Author: vishnu-77
 License-Expression: MIT

{openreflex-0.5.2 → openreflex-0.5.3}/tests/test_engine.py

@@ -149,6 +149,34 @@ def test_choose_path_accepts_custom_strategy(engine, clock):
     assert path.uncertainty == 1.0
 
 
+def test_candidate_paths_reports_explicit_choice(engine, clock):
+    engine.prompt("claude-code", "s1", "Migrate the settings loader from yaml to toml")
+    chosen = engine.choose_path("spike-then-rewrite", ["Prototype toml loader", "Swap callers"])
+
+    execution, task, paths = engine.candidate_paths()
+    assert any(p.id == chosen.id for p in paths)
+    text = engine.paths()
+    assert "OPENREFLEX / PATHS" in text
+    assert "Followed       spike-then-rewrite (explicit)" in text
+    assert "[followed]" in text
+
+
+def test_candidate_paths_reports_inferred_choice_after_finalize(engine, clock):
+    outcome, _ = run_task(engine, clock, "s1", "Fix the login bug where expired tokens are accepted", FIX_SCRIPT)
+    execution = engine.store.get(outcome.execution_id)
+    assert execution.chosen_inferred
+
+    text = engine.paths()
+    assert "inferred from tool calls" in text
+
+
+def test_candidate_paths_reports_not_yet_determined_while_running(engine, clock):
+    engine.prompt("claude-code", "s1", "Fix the login bug where expired tokens are accepted")
+
+    text = engine.paths()
+    assert "Followed       not yet determined (execution still running)" in text
+
+
 def test_compound_commands_are_categorized_by_the_program_they_run():
     from openreflex.privacy import categorize
     assert categorize("Bash", {"command": "Get-Location; rg --files -g '*test*' -g pytest.ini"}) == "search"

{openreflex-0.5.2 → openreflex-0.5.3}/tests/test_mcp_metrics_benchmark.py

@@ -23,8 +23,8 @@ def test_mcp_tools_require_approval_then_work(project, clock):
     server = build_server(project)
     names = {tool.name for tool in asyncio.run(server.list_tools())}
     assert {"get_execution_context", "choose_path", "check_progress", "record_outcome", "search_experience",
-            "explain_decision", "get_execution_trace", "get_reflex_score", "explain_node", "get_project_insights",
-            "approve_project", "forget_experience"} == names
+            "explain_decision", "get_execution_trace", "get_candidate_paths", "get_reflex_score", "explain_node",
+            "get_project_insights", "approve_project", "forget_experience"} == names
     assert "not enabled" in tool_text(server, "get_execution_context", {"task": "Fix the login redirect loop"})
     assert "Not approved" in tool_text(server, "approve_project", {})
     assert "enabled" in tool_text(server, "approve_project", {"confirm": True})
@@ -33,6 +33,7 @@ def test_mcp_tools_require_approval_then_work(project, clock):
     assert "Suggested path" in context and "Candidate paths" in context and "Pareto-efficient" in context
     assert "OPENREFLEX / WHY" in tool_text(server, "explain_decision", {})
     assert "OPENREFLEX / TRACE" in tool_text(server, "get_execution_trace", {})
+    assert "OPENREFLEX / PATHS" in tool_text(server, "get_candidate_paths", {})
     score = json.loads(tool_text(server, "get_reflex_score", {}))
     assert score["available"] is True and 0 <= score["reflex_score"] <= 100
     assert "Recorded chosen path: incremental" in tool_text(server, "choose_path", {"strategy": "incremental"})
@@ -92,5 +93,5 @@ def test_every_mcp_tool_is_fully_described(project):
         for name, schema in tool.inputSchema.get("properties", {}).items():
             assert schema.get("description"), f"{tool.name}.{name} has no description"
     read_only = {t.name for t in tools if t.annotations.readOnlyHint}
-    assert read_only == {"check_progress", "explain_decision", "get_execution_trace", "get_reflex_score",
-                         "search_experience", "explain_node", "get_project_insights"}
+    assert read_only == {"check_progress", "explain_decision", "get_execution_trace", "get_candidate_paths",
+                         "get_reflex_score", "search_experience", "explain_node", "get_project_insights"}

{openreflex-0.5.2 → openreflex-0.5.3}/tests/test_project_map.py

@@ -35,7 +35,6 @@ def test_project_map_indexes_source_symbols_and_dependencies_without_persisting_
     assert "src/auth/token_validator.py" in context
     assert "validate_expired_token" in context
     assert "pydantic" in context
-    assert "structural priors" in context
 
 
 def test_project_map_indexes_nested_manifests_with_project_relative_provenance(project):

{openreflex-0.5.2 → openreflex-0.5.3}/tests/test_reflex_index.py

@@ -1,4 +1,5 @@
 from openreflex.engine import Engine
+from openreflex.project_map import enrich_snapshot
 from openreflex.project_memory import build_snapshot, load_snapshot
 from openreflex.reflex_index import account_project_context, context_for_task, reinforce_latest_execution
 
@@ -17,6 +18,34 @@ def _auth_memory(project):
     return next(item for item in load_snapshot(project)["indexed_files"] if item["path"] == "src/auth.py")
 
 
+def test_expanded_stopwords_rank_real_content_match_above_boilerplate_only_overlap(project):
+    (project / "pyproject.toml").write_text("[project]\nname='demo'\n", encoding="utf-8")
+    (project / "src").mkdir()
+    (project / "src" / "shell_completion.py").write_text("def shell_complete():\n    pass\n", encoding="utf-8")
+    (project / "src" / "file_reader.py").write_text("def read_file():\n    pass\n", encoding="utf-8")
+    build_snapshot(project)
+    enrich_snapshot(project)
+
+    context = context_for_task(project, "Without editing any files, investigate how shell completion works")
+
+    line = next(entry for entry in context.splitlines() if entry.startswith("Likely project locations:"))
+    # file_reader.py only overlaps the query via now-stopped words ("file", "how", "any", "without");
+    # it must not outrank shell_completion.py, which matches on real content ("shell", "completion").
+    assert line.index("shell_completion.py") < line.index("file_reader.py")
+
+
+def test_terms_stem_gerund_forms_to_match_base_word(project):
+    (project / "pyproject.toml").write_text("[project]\nname='demo'\n", encoding="utf-8")
+    (project / "src").mkdir()
+    (project / "src" / "wrap_text.py").write_text("def format():\n    pass\n", encoding="utf-8")
+    build_snapshot(project)
+    enrich_snapshot(project)
+
+    context = context_for_task(project, "Investigate the wrapping behaviour")
+
+    assert "src/wrap_text.py" in context
+
+
 def test_verified_execution_reinforces_project_file_without_rewriting_structural_provenance(project, clock):
     _project_with_auth(project)
 
@@ -38,7 +67,6 @@ def test_verified_execution_reinforces_project_file_without_rewriting_structural
     context = context_for_task(project, "Fix expired token handling in auth")
     assert "src/auth.py" in context
     assert "explicit verified-success observation" in context
-    assert "structural prior" in context
 
 
 def test_repeated_verified_success_promotes_file_to_reinforced(project, clock):

{openreflex-0.5.2 → openreflex-0.5.3}/tests/test_tui_memory.py

@@ -81,6 +81,26 @@ def test_new_prompt_resets_previous_task_activity_and_calls(project):
     assert state["task"] == {"active": True, "mode": "build"}
 
 
+def test_prompt_state_captures_suggested_path_and_alternatives(project):
+    output = json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": "[OpenReflex] BUILD · debug | 1 similar past task(s) here, 1 succeeded.\n"
+                                  "Suggested path: test-first - Reproduce -> Fix -> Verify "
+                                  "(success~85%, ~18 tool calls, default prior).\n"
+                                  "Alternatives: incremental (+0.29 vs +0.30), inspect-first (dominated by test-first)\n",
+        }
+    })
+
+    _prompt_state(project, output, None)
+    state = read_state(project)
+
+    assert state["task"]["route"] == "test-first"
+    assert state["task"]["alternatives"] == "incremental (+0.29 vs +0.30), inspect-first (dominated by test-first)"
+    assert "test-first" in dashboard(project, colour=False)
+    assert "incremental (+0.29 vs +0.30)" in dashboard(project, colour=False)
+
+
 def test_verification_continuation_stays_in_verify_instead_of_remember(project):
     output = json.dumps({
         "hookSpecificOutput": {
@@ -105,6 +125,8 @@ def test_final_stop_marks_task_inactive(project):
     assert state["phase"] == "remember"
     assert state["task"]["active"] is False
     assert state["outcome"] == "success"
+    assert state["task"]["followed"] == "inspect-first"
+    assert "inspect-first" in dashboard(project, colour=False)
 
 
 def test_hook_runtime_records_plugin_manifest_version_without_cache_path(project, tmp_path):