alphaengine 0.9.2__tar.gz → 0.9.3__tar.gz

{alphaengine-0.9.2 → alphaengine-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 0.9.2
+Version: 0.9.3
 Summary: Validated research tooling for investment strategies: deflation, overfitting detection, and honest trial counts.
 Project-URL: Homepage, https://github.com/quantOSC/alphaengine
 Project-URL: Documentation, https://github.com/quantOSC/alphaengine#readme

{alphaengine-0.9.2 → alphaengine-0.9.3}/src/alphaengine/_version.py

@@ -84,4 +84,8 @@ is what a changed figure costs. The API may still move underneath it.
 # 0.9.2 IS THE SESSION, NOT THE MATHS. No computed value moved. A command
 # shows that it is working, and a run writes each step as it happens. A thesis
 # on the account can be pinned, and the run opened after that carries its id.
-__version__ = "0.9.2"
+#
+# 0.9.3 IS THE SESSION, NOT THE MATHS. No computed value moved. The math pane
+# is narrower. A sentence is shown the workflow it is choosing and what a step
+# already measured, and a finished step is not run again.
+__version__ = "0.9.3"

{alphaengine-0.9.2 → alphaengine-0.9.3}/src/alphaengine/cli.py

@@ -301,6 +301,19 @@ QUESTION_VERBS: dict[str, str] = {
 #: hand-maintained copies of this map is precisely the drift `commands.py`
 #: exists to prevent.
 QUESTION_FOR_WORKFLOW: dict[str, str] = {w: v for v, w in QUESTION_VERBS.items()}
+#: What each workflow answers, in a reader's words. The server publishes a name.
+#: A name is not a choice. These sentences describe the choice and say nothing
+#: about the order of steps inside it. The model sees the same sentences.
+_WORKFLOW_ANSWERS: dict[str, str] = {
+    "diagnose_data": "can I trust this data",
+    "screen_universe": "what in my universe is worth a look",
+    "evaluate_signal": "does this signal carry information",
+    "validate_study": "does this result hold up once you count the tries",
+    "stress_study": "where does it break",
+    "check_overlap": "is it new, or my book again",
+    "size_position": "how much of it should I hold",
+    "monitor_sleeve": "has anything crossed a line",
+}
 #: The held-back-rows marker. Probed like the rest: cp1252 renders a literal
 #: ellipsis as mojibake in exactly the place a user reads their result.
 ELLIPSIS = "…" if _UNICODE_OK else "..."
@@ -644,7 +657,8 @@ class Working:
         self._started = time.monotonic()
         sink = _SINK.get()
         if sink is not None:
-            sink(self.plain)
+            # The session paints this on the status line. It is not a trace line.
+            sink("\x1e" + self.plain)
             return self
         if not _tty():
             return self
@@ -900,18 +914,6 @@ def cmd_workflows(args: argparse.Namespace) -> int:
         say("The server offers no workflows.")
         return 0
 
-    # WHAT EACH ONE ANSWERS, in the reader's words. The server publishes a name,
-    # a version and an input contract -- correctly, since anything more would be
-    # workflow knowledge crossing the wire -- but a name is not a choice. These
-    # sentences live here, on the client, for exactly that reason: they describe
-    # what a reader is picking between and disclose nothing about how it works.
-    ANSWERS = {
-        "screen_universe": "what in my universe is worth a look",
-        "validate_study": "does this result hold up once you count the tries",
-        "size_position": "how much of it should I hold",
-        "monitor_sleeve": "has anything crossed a line",
-    }
-
     width = max(len(str(r.get("name"))) for r in rows)
     say("")
     for r in rows:
@@ -921,7 +923,7 @@ def cmd_workflows(args: argparse.Namespace) -> int:
         # the same question disagree. Same reasoning as a trial count that says
         # whether it was derived or asserted.
         repro = green("reproducible") if r.get("reproducible") else yellow("may differ")
-        say(f"  {bold(name.ljust(width))}   {ANSWERS.get(name, '')}")
+        say(f"  {bold(name.ljust(width))}   {_workflow_answer(r)}")
         say(f"  {' ' * width}   {dim('needs ' + needs)}  {DOT}  {repro}  {dim(str(r.get('version')))}")
     say("")
     say(dim("  alphaengine run <name> --data prices.csv   ") + dim(f"{DOT}  `commands run` for the flags"))
@@ -1619,12 +1621,12 @@ def _drive(run: Any, *, quiet: bool = False) -> None:
                     # with no why sent people to the traceback that no longer
                     # prints. The message came from the executor and was written
                     # to be read.
-                    say(f"  {red(CROSS)}  {bold(op)}")
-                    say(f"     {NEST} {took}")
+                    say(f"  step {n:<2}  {red(CROSS)}  {bold(op)}")
                     why = getattr(run, "last_error", None)
                     if why:
                         for line in str(why).splitlines():
-                            say(red(f"     {NEST} {line}"))
+                            say(red(f"           {line}"))
+                    say(f"           {took}")
                 if failures[key] >= 2:
                     run.status = "abandoned"
                     run.stopped = {
@@ -1639,11 +1641,13 @@ def _drive(run: Any, *, quiet: bool = False) -> None:
                 # `emit.*` seal rather than measure) and printing a blank line
                 # for it would read as a stall.
                 found = _found(seen, run)
-                say(f"  {_accent(ON)}  {found or bold(op)}")
-                say(f"     {dim(NEST)} {took}")
+                say(f"  step {n:<2}  {bold(op)}")
+                if found:
+                    say(f"           {found}")
+                say(f"           {took}")
                 rejected = getattr(run, "trace_rejected", None)
                 if rejected:
-                    say(yellow(f"    portal did not accept the series trace: {rejected}"))
+                    say(yellow(f"           portal did not accept the series trace: {rejected}"))
 
             if run.status != "open":
                 return
@@ -3223,6 +3227,51 @@ def _is_workflow(session: Any, name: str) -> bool:
         return False
 
 
+def _workflow_answer(row: dict[str, Any]) -> str:
+    """What this workflow answers, from the server when it says, else the local sentence."""
+    for key in ("answers", "purpose", "description", "summary"):
+        value = row.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return _WORKFLOW_ANSWERS.get(str(row.get("name") or ""), "")
+
+
+def _catalogue_option(row: dict[str, Any]) -> dict[str, Any]:
+    """One catalogue row, as a choice the model can tell from the others.
+
+    The name alone is why every question was landing on the same workflow.
+    The sentence, what it needs, and whether it repeats are the distinction.
+    """
+    name = str(row.get("name") or "?")
+    params: dict[str, Any] = {}
+    answers = _workflow_answer(row)
+    if answers:
+        params["answers"] = answers[:180]
+    needs = [str(item) for item in (row.get("requires") or []) if str(item)]
+    if needs:
+        params["needs"] = ", ".join(needs[:6])
+    agency = row.get("agency")
+    if agency:
+        params["agency"] = str(agency)
+    if row.get("reproducible") is True:
+        params["reproducible"] = "yes"
+    elif row.get("reproducible") is False:
+        params["reproducible"] = "no"
+    return {"op": name, "params": params, "answers": answers}
+
+
+def _prior_line(run: Any) -> str:
+    """One line of what the desk already ran, so the next question is not blind."""
+    from .client.agent import summarize_figures
+
+    workflow = str((getattr(run, "artifact", None) or {}).get("workflow") or "the last run")
+    line = f"{workflow} is {getattr(run, 'status', '')}."
+    measured = summarize_figures(getattr(run, "figures", None))
+    if measured != "(nothing yet)":
+        line = f"{line} {' '.join(measured.split())[:240]}"
+    return line
+
+
 def _ask(
     session: Any,
     url: str,
@@ -3234,6 +3283,7 @@ def _ask(
     thesis_id: str | None = None,
     thesis_name: str | None = None,
     thesis_statement: str | None = None,
+    prior: str | None = None,
     think: Callable[[str], str] | None = None,
 ) -> Any:
     """Natural language → a workflow chosen and driven by the user's own model.
@@ -3245,6 +3295,7 @@ def _ask(
     without being unsafe.
     """
     from .client import AgentDriver, AgentRefusal, Offline, ServerError
+    from .client.agent import prefer_index
     from .events import EventSink
     from .model import NoModelConfigured, build_think
 
@@ -3283,12 +3334,16 @@ def _ask(
         say(dim("The server offers no workflows, so there is nothing to choose from."))
         return None
 
-    say(f"  {_accent(STAR)}  {dim(label)}")
+    say(f"  model    {dim(label)}")
     if thesis_name:
-        say(dim(f"  thesis  {thesis_name}"))
+        say(dim(f"  thesis   {thesis_name}"))
+    if prior:
+        say(dim("  prior    " + prior.splitlines()[0][:88]))
     goal = request
     if thesis_statement:
         goal = f"{request}\n\nThesis:\n{thesis_statement}"
+    if prior:
+        goal = f"{goal}\n\nAlready on the desk:\n{prior}"
 
     # Choosing the workflow is the same shape as choosing a step: an index into
     # a list the server produced. Reusing `AgentDriver.pick` rather than writing
@@ -3296,16 +3351,22 @@ def _ask(
     driver = AgentDriver(
         think,
         goal=goal,
-        on_thought=lambda why: say(f"  {_accent(STAR)}  {_c('2;3', why)}"),
+        on_thought=lambda why: say(f"  why      {why}"),
         on_step=lambda line: say(f"  {line}"),
         sink=sink,
         provider=provider or None,
         model=model_name or None,
     )
-    options = [{"op": w.get("name", "?"), "params": {"agency": w.get("agency")}} for w in catalogue]
+    options = [_catalogue_option(w) for w in catalogue]
     try:
+        say(dim("  reading  the catalogue"))
         with Working(dim("reading the catalogue"), plain="reading the catalogue"):
-            index = driver.pick(options)
+            matched = prefer_index(request, options)
+            if matched is None:
+                index = driver.pick(options)
+            else:
+                index = matched
+                say(dim("  matched  the question uses this workflow's own words"))
         chosen = catalogue[index]
     except AgentRefusal as exc:
         say(red(f"The model did not choose a workflow: {exc}"))
@@ -3364,10 +3425,7 @@ def _ask(
         return None
 
     repro = chosen.get("reproducible")
-    say(
-        f"  {_accent(ON)}  chose {bold(name)}  "
-        + (green("reproducible") if repro else yellow("not reproducible"))
-    )
+    say(f"  workflow {bold(name)}   " + (green("reproducible") if repro else yellow("exploratory")))
 
     try:
         run = session.open(
@@ -3390,6 +3448,7 @@ def _ask(
         say(red(f"The run stopped: {exc}"))
         return None
 
+    say(dim("  result"))
     _report(run)
     if run.status == "closed":
         _publish_signals(session, run, workspace_id=workspace_id, label=None)

{alphaengine-0.9.2 → alphaengine-0.9.3}/src/alphaengine/client/agent.py

@@ -89,7 +89,11 @@ The goal, in the researcher's words:
 What has happened so far:
 {history}
 
-You may choose exactly ONE of these permitted steps:
+What has already been measured:
+{measured}
+
+You may choose exactly ONE of these permitted steps. Do not choose a step the
+history says has already finished.
 {options}
 
 Reply with ONLY a JSON object:
@@ -99,6 +103,67 @@ Choose the index of the step that best advances the goal. You may not invent a
 step, and you may not choose anything not listed above.
 """
 
+_STOPWORDS = frozenset(
+    {
+        "a",
+        "an",
+        "the",
+        "this",
+        "that",
+        "these",
+        "those",
+        "with",
+        "from",
+        "into",
+        "over",
+        "once",
+        "your",
+        "you",
+        "are",
+        "was",
+        "were",
+        "been",
+        "have",
+        "has",
+        "had",
+        "does",
+        "did",
+        "can",
+        "what",
+        "which",
+        "where",
+        "when",
+        "who",
+        "how",
+        "and",
+        "or",
+        "not",
+        "for",
+        "its",
+        "about",
+        "just",
+        "than",
+        "then",
+        "them",
+        "they",
+        "my",
+        "our",
+        "of",
+        "to",
+        "in",
+        "on",
+        "is",
+        "it",
+        "be",
+        "as",
+        "at",
+        "by",
+        "if",
+        "so",
+        "we",
+    }
+)
+
 
 class AgentDriver:
     """Drives a run by asking a model which permitted step to take next.
@@ -144,14 +209,14 @@ class AgentDriver:
         and cannot name an op. This wrapper is the prompt+goal layer that USES it.
         """
 
-        def choose(permitted: list[Figures], _figures: Figures) -> int:
-            return self.pick(permitted)
+        def choose(permitted: list[Figures], figures: Figures) -> int:
+            return self.pick(permitted, figures)
 
         return choose
 
     # ── the one decision ───────────────────────────────────────────────────
 
-    def pick(self, permitted: list[Figures]) -> int:
+    def pick(self, permitted: list[Figures], figures: Any = None) -> int:
         """Return an INDEX into `permitted`. Never a step, never an op name.
 
         The index is the safety property. A model cannot name an operation the
@@ -172,6 +237,7 @@ class AgentDriver:
         prompt = _PROMPT.format(
             goal=self.goal,
             history="\n".join(f"  - {h}" for h in self.history[-12:]) or "  (nothing yet)",
+            measured=summarize_figures(figures),
             options=options,
         )
         raw = self.think(prompt)
@@ -213,34 +279,63 @@ class AgentDriver:
         """
         n = 0
         failures: dict[str, int] = {}
+        done_ids: set[str] = set()
+        done_sigs: set[str] = set()
         while run.status == "open" and n < self.max_steps:
             if not run.permitted:
                 run.resume()
                 if run.status != "open" or not run.permitted:
                     break
 
-            step = run.permitted[self.pick(run.permitted)]
-            op = str(step.get("op") or "?")
-            self.on_step(f"{n + 1}  {op}")
-            before = run.status
-            started = time.monotonic()
-            run.step(step)
-            took = time.monotonic() - started
-            n += 1
-
-            still = any(p.get("step_id") == step.get("step_id") for p in run.permitted)
-            if still and before == "open" and run.status == "open":
-                key = str(step.get("step_id"))
-                failures[key] = failures.get(key, 0) + 1
-                self.history.append(f"{op} could not be executed here")
-                self.on_step(f"{n}  {op}  could not be executed  {took:.1f}s")
-                if failures[key] >= 2:
-                    run.status = "abandoned"
-                    run.stopped = {"reason": "step_failed", "op": step.get("op")}
-                    return run
+            fresh = [p for p in run.permitted if not _already_done(p, done_ids, done_sigs)]
+            if not fresh:
+                op = str((run.permitted[0] or {}).get("op") or "?")
+                self.on_step(f"stop     {op} already finished")
+                self.history.append(f"{op} already finished; not running it again")
+                run.status = "stopped"
+                run.stopped = {"reason": "already finished", "op": op}
+                return run
+
+            if getattr(run, "selection", None) == "all":
+                batch = list(fresh)
+            elif len(fresh) == 1:
+                batch = fresh
             else:
-                self.history.append(f"{op} done")
-                self.on_step(f"{n}  {op}  {took:.1f}s")
+                batch = [fresh[self.pick(fresh, getattr(run, "figures", None))]]
+
+            for step in batch:
+                op = str(step.get("op") or "?")
+                self.on_step(f"step {n + 1:<2}  {op}")
+                before = run.status
+                started = time.monotonic()
+                run.step(step)
+                took = time.monotonic() - started
+                n += 1
+
+                still = any(p.get("step_id") == step.get("step_id") for p in run.permitted)
+                if still and before == "open" and run.status == "open":
+                    key = str(step.get("step_id"))
+                    failures[key] = failures.get(key, 0) + 1
+                    self.history.append(f"{op} could not be executed here")
+                    self.on_step(f"         could not be executed   {took:.1f}s")
+                    if failures[key] >= 2:
+                        run.status = "abandoned"
+                        run.stopped = {"reason": "step_failed", "op": step.get("op")}
+                        return run
+                else:
+                    sid = str(step.get("step_id") or "")
+                    if sid:
+                        done_ids.add(sid)
+                    done_sigs.add(_signature(step))
+                    found = _finding(getattr(run, "figures", None), op)
+                    note = f"{op} finished"
+                    if found:
+                        note += f" ({found})"
+                    self.history.append(note)
+                    detail = f"         {found}   {took:.1f}s" if found else f"         {took:.1f}s"
+                    self.on_step(detail)
+                if run.status != "open":
+                    return run
 
         if run.status == "open" and n >= self.max_steps:
             raise AgentRefusal(
@@ -253,6 +348,95 @@ class AgentDriver:
 # ── parsing, which has to assume the model is sloppy ───────────────────────
 
 
+def summarize_figures(figures: Any, *, limit: int = 8) -> str:
+    """Scalars the run already produced. Lists stay out: a list is a series."""
+    if not isinstance(figures, dict) or not figures:
+        return "(nothing yet)"
+    lines: list[str] = []
+    for op, blob in figures.items():
+        if not isinstance(blob, dict):
+            continue
+        bits = _scalar_bits(blob)
+        if bits:
+            lines.append(f"  {op}: " + ", ".join(bits))
+        if len(lines) >= limit:
+            break
+    return "\n".join(lines) or "(nothing yet)"
+
+
+def _scalar_bits(blob: dict[str, Any], limit: int = 4) -> list[str]:
+    bits: list[str] = []
+    for key, value in blob.items():
+        if isinstance(value, bool) or value is None:
+            continue
+        if isinstance(value, float):
+            bits.append(f"{key}={value:.4g}")
+        elif isinstance(value, int):
+            bits.append(f"{key}={value}")
+        elif isinstance(value, str) and value.strip() and len(value) <= 80:
+            bits.append(f"{key}={value.strip()}")
+        if len(bits) >= limit:
+            break
+    return bits
+
+
+def _finding(figures: Any, op: str) -> str:
+    if not isinstance(figures, dict):
+        return ""
+    blob = figures.get(op)
+    if not isinstance(blob, dict):
+        return ""
+    return ", ".join(_scalar_bits(blob))
+
+
+def _signature(step: dict[str, Any]) -> str:
+    """Same op and same params is the same step, even with a new id."""
+    return f"{step.get('op') or ''}|{_brief(step.get('params') or {})}"
+
+
+def _already_done(step: dict[str, Any], done_ids: set[str], done_sigs: set[str]) -> bool:
+    sid = str(step.get("step_id") or "")
+    if sid and sid in done_ids:
+        return True
+    return _signature(step) in done_sigs
+
+
+def prefer_index(question: str, options: list[dict[str, Any]]) -> int | None:
+    """The one option whose own words the question uses.
+
+    None when the question does not single one out. There is no default and
+    no preferred order: a tie, or a weak overlap, goes to the model.
+    """
+    if not options:
+        return None
+    question_l = question.lower()
+    q = _content_tokens(question)
+    q_words = set(re.findall(r"[a-z0-9]+", question_l))
+    scores: list[int] = []
+    for opt in options:
+        answers = opt.get("answers")
+        if not isinstance(answers, str):
+            params = opt.get("params")
+            answers = params.get("answers") if isinstance(params, dict) else ""
+        score = len(q & _content_tokens(str(answers or "")))
+        name = str(opt.get("op") or "").lower()
+        if name and name.replace("_", " ") in question_l:
+            score += 3
+        for piece in name.split("_"):
+            if len(piece) >= 4 and piece in q_words:
+                score += 2
+        scores.append(score)
+    best = max(scores)
+    if best < 2:
+        return None
+    winners = [i for i, score in enumerate(scores) if score == best]
+    return winners[0] if len(winners) == 1 else None
+
+
+def _content_tokens(text: str) -> set[str]:
+    return {w for w in re.findall(r"[a-z0-9]+", text.lower()) if len(w) >= 4 and w not in _STOPWORDS}
+
+
 def _brief(params: Any) -> str:
     """A short, SAFE rendering of a step's params for the prompt.
 

{alphaengine-0.9.2 → alphaengine-0.9.3}/src/alphaengine/tui/app.py

@@ -66,8 +66,8 @@ Screen { background: #0b0d10; }
     padding: 0 1;
 }
 #inspector {
-    width: 44;
-    min-width: 36;
+    width: 30;
+    min-width: 24;
     background: #101318;
     padding: 1 1;
     overflow: hidden;
@@ -437,6 +437,15 @@ class QuantOSApp(App[None]):
         self.query_one("#status", Static).update(f"{frame}   working   ·   {label}   ·   {elapsed:.1f}s")
 
     def _live(self, chunk: str) -> None:
+        # A working label updates the status line and does not join the trace.
+        # The step lines are the trace; a second copy of the op name is noise.
+        if chunk.startswith("\x1e"):
+            label = _plain(chunk[1:]).strip()
+            if label:
+                self.activity = label
+            if self.busy:
+                self._paint_working()
+            return
         plain = _plain(chunk).strip()
         if not plain:
             return

{alphaengine-0.9.2 → alphaengine-0.9.3}/src/alphaengine/tui/dispatch.py

@@ -22,6 +22,7 @@ from ..cli import (
     _help_text,
     _is_workflow,
     _near_verb,
+    _prior_line,
     _repl_gap,
     _report,
     _split_run,
@@ -487,6 +488,7 @@ def _sentence(desk: Desk, line: str) -> None:
         thesis_id=thesis_id_of(pinned) or None if pinned else None,
         thesis_name=thesis_label(pinned) if pinned else None,
         thesis_statement=thesis_text(pinned) if pinned else None,
+        prior=_prior_line(desk.last) if desk.last is not None else None,
     )
     if run is not None:
         desk.last = run

{alphaengine-0.9.2 → alphaengine-0.9.3}/tests/test_agent.py

@@ -134,6 +134,66 @@ def test_as_choice_is_the_index_bound_primitive():
     assert callable(IndexDriver)
 
 
+def test_measured_scalars_reach_the_model_and_series_do_not():
+    """A later choice that cannot see what the last step found picks the same
+    step again. The scalars go in. A list is a series and stays out."""
+    seen: list[str] = []
+
+    def think(prompt: str) -> str:
+        seen.append(prompt)
+        return '{"choice": 1, "why": "the sweep already reported"}'
+
+    AgentDriver(think, goal="g").pick(
+        PERMITTED,
+        {"compute.sweep": {"sharpe": 0.4, "curve": [1, 2, 3], "verdict": "stop"}},
+    )
+    assert "compute.sweep" in seen[0]
+    assert "sharpe=0.4" in seen[0]
+    assert "verdict=stop" in seen[0]
+    assert "[1, 2, 3]" not in seen[0]
+
+
+def test_a_finished_step_is_not_executed_again():
+    """A new step id with the same op and the same params is the same work.
+    Running it again is how a sentence loops."""
+
+    class _Replay:
+        def __init__(self) -> None:
+            self.status = "open"
+            self.selection = "any"
+            self.permitted = [{"step_id": "s1", "op": "compute.screen", "params": {}}]
+            self.figures: dict = {}
+            self.calls = 0
+            self.stopped = None
+
+        def resume(self) -> None:
+            return None
+
+        def step(self, step: dict) -> None:
+            self.calls += 1
+            self.figures["compute.screen"] = {"sharpe": 1.25}
+            self.permitted = [{"step_id": "s9", "op": "compute.screen", "params": {}}]
+            self.status = "open"
+
+    run = _Replay()
+    AgentDriver(lambda _p: '{"choice": 0}', goal="g").drive(run)
+    assert run.calls == 1
+    assert run.status == "stopped"
+    assert run.stopped["reason"] == "already finished"
+
+
+def test_a_question_that_names_one_workflow_is_not_left_to_guess():
+    from alphaengine.client.agent import prefer_index
+
+    options = [
+        {"op": "screen_universe", "answers": "what in my universe is worth a look"},
+        {"op": "validate_study", "answers": "does this result hold up once you count the tries"},
+    ]
+    assert prefer_index("screen my universe", options) == 0
+    assert prefer_index("which of my names are overbought", options) is None
+    assert prefer_index("look at the universe and validate the study", options) is None
+
+
 def test_params_are_truncated_before_reaching_the_model():
     """A step's params can carry a parameter grid, which is frequently bigger
     intellectual property than the returns. No reason to ship all of it to a