alphaengine 0.9.1__tar.gz → 0.9.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 0.9.1
+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
@@ -333,6 +333,7 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 |---|---|---|
 | `book [<name> \| status]` | show or load sleeves on the multi-strategy book | session |
 | `load <file \| module \| universe>` | a CSV, a project module, or a portal universe | session |
+| `thesis [<name> \| clear]` | choose a portal thesis for the next run | session |
 | `universe <name>` | same as load: a universe registered in the portal | session |
 | `data <file>` | same as load: a local CSV or parquet | session |
 | `project <module>` | same as load: a module with data and backtest_fn | session |
@@ -363,6 +364,7 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `--project MODULE` | a module exposing `data` and `backtest_fn` |
 | `--data FILE` | a local CSV: wide, long, or a single series |
 | `--universe NAME` | a universe registered in the portal, with its stored closes |
+| `--thesis NAME` | a thesis on this account; the run is attached to it |
 | `--symbol TICKER` | one name out of a loaded universe; its closes become the return series |
 | `--label TEXT` | what to call the artifact this run produces |
 | `--input K=V` | a workflow input; repeatable |
@@ -398,6 +400,7 @@ alphaengine run size_position --data returns.csv
 alphaengine run validate_study --project research.momentum
 alphaengine models
 alphaengine trace
+alphaengine run screen_universe --thesis momentum
 alphaengine logout
 alphaengine version
 ```

{alphaengine-0.9.1 → alphaengine-0.9.3}/README.md

@@ -288,6 +288,7 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 |---|---|---|
 | `book [<name> \| status]` | show or load sleeves on the multi-strategy book | session |
 | `load <file \| module \| universe>` | a CSV, a project module, or a portal universe | session |
+| `thesis [<name> \| clear]` | choose a portal thesis for the next run | session |
 | `universe <name>` | same as load: a universe registered in the portal | session |
 | `data <file>` | same as load: a local CSV or parquet | session |
 | `project <module>` | same as load: a module with data and backtest_fn | session |
@@ -318,6 +319,7 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `--project MODULE` | a module exposing `data` and `backtest_fn` |
 | `--data FILE` | a local CSV: wide, long, or a single series |
 | `--universe NAME` | a universe registered in the portal, with its stored closes |
+| `--thesis NAME` | a thesis on this account; the run is attached to it |
 | `--symbol TICKER` | one name out of a loaded universe; its closes become the return series |
 | `--label TEXT` | what to call the artifact this run produces |
 | `--input K=V` | a workflow input; repeatable |
@@ -353,6 +355,7 @@ alphaengine run size_position --data returns.csv
 alphaengine run validate_study --project research.momentum
 alphaengine models
 alphaengine trace
+alphaengine run screen_universe --thesis momentum
 alphaengine logout
 alphaengine version
 ```

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

@@ -80,4 +80,12 @@ is what a changed figure costs. The API may still move underneath it.
 # 0.9.1 IS THE SESSION, NOT THE MATHS. No computed value moved. A signed-in
 # account loads its one stored universe from the portal. `enter model key`
 # takes whichever provider key is pasted. The left pane lists the commands.
-__version__ = "0.9.1"
+#
+# 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.
+#
+# 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.1 → 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
@@ -1708,11 +1712,28 @@ def cmd_run(args: argparse.Namespace) -> int:
         # named one explicitly. Without this, a sweep received `grid={}`.
         if "grid" not in inputs and project_grid():
             inputs["grid"] = project_grid()
+        thesis_id = None
+        named_thesis = getattr(args, "thesis", None)
+        if named_thesis:
+            chosen, candidates = match_thesis(session.theses(), str(named_thesis))
+            if chosen is None:
+                if candidates:
+                    names = ", ".join(thesis_label(r) for r in candidates)
+                    say(yellow(f"Which thesis? {names}"))
+                else:
+                    say(yellow(f"No thesis named {named_thesis!r} on this account."))
+                return 2
+            thesis_id = thesis_id_of(chosen)
+            if not thesis_id:
+                say(yellow(f"{thesis_label(chosen)} has no id, so a run cannot be attached to it."))
+                return 2
+            say(dim(f"  thesis  {thesis_label(chosen)}"))
         run = session.open(
             args.workflow,
             data=data,
             backtest_fn=backtest_fn,
             workspace_id=workspace_id,
+            thesis_id=thesis_id,
             **inputs,
         )
         _drive(run, quiet=args.quiet)
@@ -2235,7 +2256,7 @@ def _extract_flags(line: str) -> tuple[str, list[str]]:
     i = 0
     while i < len(parts):
         tok = parts[i]
-        if tok in ("--data", "--universe", "--project", "--symbol") and i + 1 < len(parts):
+        if tok in ("--data", "--universe", "--project", "--symbol", "--thesis") and i + 1 < len(parts):
             flags += [tok, parts[i + 1]]
             i += 2
             continue
@@ -2357,6 +2378,58 @@ def _stored_universes(session: Any, question: str = "") -> tuple[str | None, lis
     return (ready[0] if len(ready) == 1 else None), ready
 
 
+def thesis_label(row: dict[str, Any]) -> str:
+    """The name a person types. The id is what the run carries."""
+    return str(row.get("name") or row.get("title") or row.get("id") or "").strip()
+
+
+def thesis_text(row: dict[str, Any]) -> str:
+    """The statement, under whichever key the portal sent it."""
+    for key in ("statement", "summary", "body", "text"):
+        value = row.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return ""
+
+
+def thesis_id_of(row: dict[str, Any]) -> str:
+    return str(row.get("id") or row.get("thesis_id") or "").strip()
+
+
+def match_thesis(rows: list[Any], query: str) -> tuple[dict[str, Any] | None, list[dict[str, Any]]]:
+    """One thesis, or the candidates when the name matches more than one.
+
+    Exact name or id wins. A unique substring is enough. Several matches are
+    returned so the caller can name them instead of guessing.
+    """
+    usable = [r for r in rows if isinstance(r, dict)]
+    q = query.strip().casefold()
+    exact = [r for r in usable if thesis_label(r).casefold() == q or thesis_id_of(r).casefold() == q]
+    if len(exact) == 1:
+        return exact[0], []
+    if len(exact) > 1:
+        return None, exact
+    partial = [r for r in usable if q and q in thesis_label(r).casefold()]
+    if len(partial) == 1:
+        return partial[0], []
+    return None, partial
+
+
+def pop_flag(flags: list[str], name: str) -> tuple[str | None, list[str]]:
+    """Take one ``--name value`` out of a flag list. The rest stay in order."""
+    kept: list[str] = []
+    value: str | None = None
+    i = 0
+    while i < len(flags):
+        if flags[i] == name and i + 1 < len(flags):
+            value = flags[i + 1]
+            i += 2
+            continue
+        kept.append(flags[i])
+        i += 1
+    return value, kept
+
+
 def _split_run(rest: str) -> tuple[str, list[str]]:
     """`screen_universe --universe sp100` -> ("screen_universe", [...]).
 
@@ -3154,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,
@@ -3162,6 +3280,10 @@ def _ask(
     data: Any,
     backtest_fn: Any,
     workspace_id: str | None = None,
+    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.
@@ -3173,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
 
@@ -3211,23 +3334,39 @@ 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}"))
+    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
     # a second selector keeps one place where a model's answer is validated.
     driver = AgentDriver(
         think,
-        goal=request,
-        on_thought=lambda why: say(f"  {_accent(STAR)}  {_c('2;3', why)}"),
+        goal=goal,
+        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}"))
@@ -3286,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(
@@ -3297,6 +3433,7 @@ def _ask(
             data=data,
             backtest_fn=backtest_fn,
             workspace_id=workspace_id,
+            thesis_id=thesis_id,
             **({"grid": project_grid()} if project_grid() else {}),
         )
         sink.bind(run.run_id)
@@ -3311,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)
@@ -3520,6 +3658,7 @@ def build_parser() -> argparse.ArgumentParser:
     r = sub.add_parser("run", parents=[common], help="run one workflow to completion")
     r.add_argument("workflow")
     r.add_argument("--label", help="what to call the artifact")
+    r.add_argument("--thesis", help="name or id of a thesis on this account; attached to the run")
     r.add_argument("--input", action="append", help="workflow input as key=value (repeatable)")
     r.add_argument("--quiet", action="store_true", help="only the result")
     r.add_argument("--stream", action="store_true", help="print the answer after the citation guard")
@@ -3532,6 +3671,7 @@ def build_parser() -> argparse.ArgumentParser:
     for verb, workflow in QUESTION_VERBS.items():
         q = sub.add_parser(verb, parents=[common], help=f"run {workflow}")
         q.add_argument("--label", help="what to call the artifact")
+        q.add_argument("--thesis", help="name or id of a thesis on this account; attached to the run")
         q.add_argument("--input", action="append", help="workflow input as key=value (repeatable)")
         q.add_argument("--quiet", action="store_true", help="only the result")
         q.add_argument("--stream", action="store_true", help="print the answer after the citation guard")