alphaengine 0.9.1__tar.gz → 0.9.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 0.9.1
+Version: 0.9.2
 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.2}/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.2}/src/alphaengine/_version.py

@@ -80,4 +80,8 @@ 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.
+__version__ = "0.9.2"

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

@@ -1708,11 +1708,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 +2252,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 +2374,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", [...]).
 
@@ -3162,6 +3231,9 @@ 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,
     think: Callable[[str], str] | None = None,
 ) -> Any:
     """Natural language → a workflow chosen and driven by the user's own model.
@@ -3212,14 +3284,20 @@ def _ask(
         return None
 
     say(f"  {_accent(STAR)}  {dim(label)}")
+    if thesis_name:
+        say(dim(f"  thesis  {thesis_name}"))
+    goal = request
+    if thesis_statement:
+        goal = f"{request}\n\nThesis:\n{thesis_statement}"
 
     # 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,
+        goal=goal,
         on_thought=lambda why: say(f"  {_accent(STAR)}  {_c('2;3', why)}"),
+        on_step=lambda line: say(f"  {line}"),
         sink=sink,
         provider=provider or None,
         model=model_name or None,
@@ -3297,6 +3375,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)
@@ -3520,6 +3599,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 +3612,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")

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

@@ -47,6 +47,7 @@ from __future__ import annotations
 
 import json
 import re
+import time
 from collections.abc import Callable
 from typing import Any, Protocol
 
@@ -115,6 +116,7 @@ class AgentDriver:
         *,
         goal: str,
         on_thought: Callable[[str], None] | None = None,
+        on_step: Callable[[str], None] | None = None,
         max_steps: int = 60,
         sink: Any | None = None,
         provider: str | None = None,
@@ -126,6 +128,9 @@ class AgentDriver:
         # A loop you cannot watch is a loop you cannot trust, and that applies
         # doubly when something non-deterministic is making the choices.
         self.on_thought = on_thought or (lambda _s: None)
+        # A second narrator for the step itself, so a watched run can show the
+        # op while it is still running and the duration once it returns.
+        self.on_step = on_step or (lambda _s: None)
         self.max_steps = max_steps
         self.history: list[str] = []
         self.sink = sink
@@ -215,21 +220,27 @@ class AgentDriver:
                     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"{step.get('op')} could not be executed here")
+                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
             else:
-                self.history.append(f"{step.get('op')} done")
+                self.history.append(f"{op} done")
+                self.on_step(f"{n}  {op}  {took:.1f}s")
 
         if run.status == "open" and n >= self.max_steps:
             raise AgentRefusal(

{alphaengine-0.9.1 → alphaengine-0.9.2}/src/alphaengine/client/session.py

@@ -335,6 +335,7 @@ class Session:
         backtest_fn: Any = None,
         handlers: dict[str, Handler] | None = None,
         workspace_id: str | None = None,
+        thesis_id: str | None = None,
         **inputs: Any,
     ) -> Run:
         """Open a run. `data` and `backtest_fn` stay on this machine.
@@ -345,10 +346,15 @@ class Session:
         into the pod's book. Without it the run is complete, correct, and
         attached to nothing — which is why several finished mechanisms on the
         platform had never once received input.
+
+        `thesis_id` names a thesis the portal already holds. The statement
+        stays on this machine; the id is how the run is attached to it.
         """
         body: Figures = {"workflow": workflow, "version": version, "inputs": inputs}
         if workspace_id:
             body["workspace_id"] = workspace_id
+        if thesis_id:
+            body["thesis_id"] = thesis_id
         directive = self._post("/api/harness/runs", body)
         run = Run(
             session=self,
@@ -486,17 +492,19 @@ class Session:
         q = f"?budget={int(budget)}" if budget else ""
         return self._get(f"/api/harness/plan{q}")
 
-    # ── THE THESIS AND SLEEVE METHODS ARE GONE (0.5.0) ─────────────────────
-    #
-    # `theses()`, `propose_sleeve()` and `sleeves()` backed `--thesis` and
-    # `--sleeve`. Their routes — /api/me/theses, /api/me/proposals/from-os and
-    # /api/me/sleeves — were part of the thesis object model, which came out with
-    # the retired agent desk it was built around.
-    #
-    # A breaking change, and a deliberate one: they created a PROPOSAL from a
-    # screen, which is the one thing this package ever made, and the loop that
-    # object served now runs through assignments and the deliver pin instead.
-    # See the 0.5.0 note in the README.
+    def theses(self) -> list[Figures]:
+        """Theses on this account. Names and statements. No market data.
+
+        ``GET /api/me/theses`` returns ``{"theses": [{"id", "name", "statement"}]}``.
+        ``summary`` is accepted as the statement when ``statement`` is absent.
+        The id is what a later ``open`` sends back as ``thesis_id``. This call
+        does not create a thesis and does not write a proposal.
+        """
+        return list(self._get("/api/me/theses").get("theses") or [])
+
+    # `propose_sleeve()` and `sleeves()` backed `--sleeve` and wrote a proposal
+    # to `/api/me/proposals/from-os` and `/api/me/sleeves`. Those left with the
+    # agent desk in 0.5.0. Selecting a thesis is the read above, not that writer.
 
     def post_event(self, run_id: str, event: dict[str, Any]) -> Figures:
         """Allowlisted model/run event. 404-tolerant at the sink, not here.

{alphaengine-0.9.1 → alphaengine-0.9.2}/src/alphaengine/commands.py

@@ -84,6 +84,7 @@ FLAGS: dict[str, Flag] = {
     "project": Flag("--project", "MODULE", "a module exposing `data` and `backtest_fn`"),
     "data": Flag("--data", "FILE", "a local CSV: wide, long, or a single series"),
     "universe": Flag("--universe", "NAME", "a universe registered in the portal, with its stored closes"),
+    "thesis": Flag("--thesis", "NAME", "a thesis on this account; the run is attached to it"),
     "symbol": Flag(
         "--symbol", "TICKER", "one name out of a loaded universe; its closes become the return series"
     ),
@@ -352,7 +353,19 @@ COMMANDS: tuple[Command, ...] = _question_commands() + (
             "alphaengine run size_position --data returns.csv",
             "alphaengine run validate_study --project research.momentum",
         ),
-        flags=("project", "data", "universe", "symbol", "label", "input", "quiet", "stream", "url", "key"),
+        flags=(
+            "project",
+            "data",
+            "universe",
+            "symbol",
+            "thesis",
+            "label",
+            "input",
+            "quiet",
+            "stream",
+            "url",
+            "key",
+        ),
     ),
     Command(
         verb="<anything else>",
@@ -454,6 +467,29 @@ COMMANDS: tuple[Command, ...] = _question_commands() + (
         ),
         examples=("load prices.csv", "load research.momentum", "load sp500"),
     ),
+    Command(
+        verb="thesis",
+        group="data",
+        args="[<name> | clear]",
+        scope="repl",
+        purpose="choose a portal thesis for the next run",
+        body=(
+            "Lists the theses on this account, or pins one. A pinned thesis rides on "
+            "every following run, question, and workflow as thesis_id. The statement "
+            "stays on this machine and is given to your model as context. It is not "
+            "written into the figures.\n\n"
+            "`thesis clear` unpins it. One thesis on the account is pinned at sign-in. "
+            "Several are named and not guessed.\n\n"
+            "The shell spelling is `--thesis <name>` on `run`, `screen`, `diagnose`, "
+            "and the other question commands."
+        ),
+        examples=(
+            "thesis",
+            "thesis momentum",
+            "thesis clear",
+            "alphaengine run screen_universe --thesis momentum",
+        ),
+    ),
     Command(
         verb="universe",
         group="data",

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

@@ -5,13 +5,14 @@ from __future__ import annotations
 import argparse
 import os
 import re
+import time
 from typing import Any
 
 from textual.app import App, ComposeResult
 from textual.containers import Horizontal, Vertical
 from textual.widgets import DataTable, Input, ListItem, ListView, RichLog, Sparkline, Static
 
-from ..cli import narration_to, resolve_data
+from ..cli import narration_to, resolve_data, thesis_id_of, thesis_label
 from .dispatch import Desk, submit
 
 _ANSI = re.compile(r"\x1b\[[0-9;]*m")
@@ -20,6 +21,7 @@ _COMMANDS = (
     "login",
     "enter model key",
     "load <name>",
+    "thesis",
     "screen",
     "diagnose",
     "signal",
@@ -37,6 +39,7 @@ _URL_AFTER = {
     "AZURE_OPENAI_API_KEY": "AZURE_OPENAI_ENDPOINT",
     "ALPHAENGINE_API_KEY": "ALPHAENGINE_BASE_URL",
 }
+_SPIN = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
 
 _CSS = """
 Screen { background: #0b0d10; }
@@ -131,6 +134,8 @@ class QuantOSApp(App[None]):
         self._stored: set[str] = set()
         self._lines: list[dict[str, Any]] = []
         self.busy = False
+        self.activity = ""
+        self._started = 0.0
         self.rail_text = ""
         self.formula_text = ""
         self.transcript: list[str] = []
@@ -160,6 +165,7 @@ class QuantOSApp(App[None]):
         log.write("")
         log.write("help lists what you can type.  quit leaves.")
         self.query_one(Input).focus()
+        self.set_interval(0.2, self._tick_working)
         self._sync_account()
 
     def _refresh_rail(self) -> None:
@@ -200,6 +206,9 @@ class QuantOSApp(App[None]):
             "loaded",
             f"  {loaded}",
             "",
+            "thesis",
+            f"  {_fit(thesis_label(self.desk.thesis) if self.desk.thesis else 'none')}",
+            "",
             "universes",
         ]
         if self._universes:
@@ -239,6 +248,11 @@ class QuantOSApp(App[None]):
             self._accept_url(text)
             return
         self.busy = True
+        self.activity = text
+        self._started = time.monotonic()
+        prompt = self.query_one(Input)
+        prompt.disabled = True
+        self._paint_working()
         self.query_one("#transcript", RichLog).write(f"> {text}")
 
         def go() -> None:
@@ -393,6 +407,17 @@ class QuantOSApp(App[None]):
                     notes.append(
                         "Stored on your account: " + ", ".join(ready) + ".  Type load <name> to use one."
                     )
+        if self.desk.keyed and self.desk.thesis is None and not self.desk.thesis_declined:
+            try:
+                theses = [r for r in self.desk.session.theses() if isinstance(r, dict) and thesis_id_of(r)]
+            except Exception:  # noqa: BLE001 — offline or unsigned still boots
+                theses = []
+            if len(theses) == 1:
+                self.desk.thesis = theses[0]
+                notes.append(f"thesis {thesis_label(theses[0])}")
+            elif len(theses) > 1:
+                named = ", ".join(thesis_label(r) for r in theses[:8])
+                notes.append(f"Theses on your account: {named}.  Type thesis <name> to use one.")
         log = self.query_one("#transcript", RichLog)
         for note in notes:
             plain = _plain(note)
@@ -401,46 +426,64 @@ class QuantOSApp(App[None]):
                 log.write(plain)
         self._refresh_rail()
 
+    def _tick_working(self) -> None:
+        if self.busy:
+            self._paint_working()
+
+    def _paint_working(self) -> None:
+        elapsed = time.monotonic() - self._started
+        frame = _SPIN[int(elapsed * 12) % len(_SPIN)]
+        label = _fit(self.activity or "working", 42)
+        self.query_one("#status", Static).update(f"{frame}   working   ·   {label}   ·   {elapsed:.1f}s")
+
+    def _live(self, chunk: str) -> None:
+        plain = _plain(chunk).strip()
+        if not plain:
+            return
+        self.activity = plain
+        self.transcript.append(plain)
+        self.query_one("#transcript", RichLog).write(plain)
+        if self.busy:
+            self._paint_working()
+
     def _run_line(self, text: str) -> None:
-        chunks: list[str] = []
+        quitting = False
 
         def sink(chunk: str) -> None:
-            chunks.append(chunk)
+            self.call_from_thread(self._live, chunk)
 
-        quitting = False
         try:
             with narration_to(sink):
                 quitting = submit(self.desk, text)
         except Exception as exc:  # noqa: BLE001 — the session stays up
-            chunks.append(str(exc))
-        self.call_from_thread(self._finish, chunks, quitting)
+            self.call_from_thread(self._live, str(exc))
+        self.call_from_thread(self._finish, quitting)
 
-    def _finish(self, chunks: list[str], quitting: bool) -> None:
-        log = self.query_one("#transcript", RichLog)
-        for chunk in chunks:
-            plain = _plain(chunk)
-            if plain.strip():
-                self.transcript.append(plain)
-                log.write(plain)
+    def _finish(self, quitting: bool) -> None:
+        prompt = self.query_one(Input)
+        prompt.disabled = False
         if self.desk.pending_secret:
-            prompt = self.query_one(Input)
             prompt.password = True
             prompt.placeholder = "paste the key (hidden)"
         elif self.desk.pending_provider:
-            prompt = self.query_one(Input)
             prompt.password = False
             prompt.placeholder = "anthropic, openai, gemini, groq, openrouter, azure, gateway"
         elif self.desk.pending_url:
-            prompt = self.query_one(Input)
             prompt.password = False
             prompt.placeholder = f"paste {self.desk.pending_url}"
+        else:
+            prompt.password = False
+            prompt.placeholder = "Ask in plain English, or run <workflow>"
+        self.busy = False
+        self.activity = ""
         if self.desk.account_dirty:
             self.desk.account_dirty = False
             self._sync_account()
         else:
             self._refresh_rail()
         self._load_lines()
-        self.busy = False
+        if not quitting:
+            prompt.focus()
         if quitting:
             self.exit()
 

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

@@ -27,11 +27,16 @@ from ..cli import (
     _split_run,
     dim,
     load_project,
+    match_thesis,
+    pop_flag,
     preflight,
     project_grid,
     red,
     resolve_data,
     say,
+    thesis_id_of,
+    thesis_label,
+    thesis_text,
     yellow,
 )
 from ..client import Offline, ServerError
@@ -57,6 +62,8 @@ class Desk:
     account_dirty: bool = False
     pinned_model: str | None = None
     book: Any = None
+    thesis: dict[str, Any] | None = None
+    thesis_declined: bool = False
 
 
 def submit(desk: Desk, line: str) -> bool:
@@ -66,6 +73,9 @@ def submit(desk: Desk, line: str) -> bool:
         return False
 
     line, inline_flags = _extract_flags(line)
+    thesis_query, inline_flags = pop_flag(inline_flags, "--thesis")
+    if thesis_query and not _pin_thesis(desk, thesis_query):
+        return False
     if inline_flags:
         try:
             desk.data, desk.backtest_fn = _apply_flags(
@@ -78,8 +88,8 @@ def submit(desk: Desk, line: str) -> bool:
         except Exception as exc:  # noqa: BLE001 — a server refusal, said plainly
             say(red(str(exc)))
             return False
-        if not line.strip():
-            return False
+    if not line.strip():
+        return False
 
     if line.split()[:1] == ["alphaengine"]:
         line = line.partition(" ")[2].strip()
@@ -132,6 +142,9 @@ def submit(desk: Desk, line: str) -> bool:
     if verb == "book":
         _book(desk, rest)
         return False
+    if verb in ("thesis", "theses"):
+        _thesis(desk, rest)
+        return False
     if verb in ("commands", "?"):
         from ..cli import cmd_commands
 
@@ -164,6 +177,8 @@ def submit(desk: Desk, line: str) -> bool:
         _key(desk, rest)
         return False
     if verb == "status":
+        if desk.thesis:
+            say(dim(f"thesis {thesis_label(desk.thesis)}"))
         if desk.last is None:
             say(dim("no run yet"))
         else:
@@ -232,6 +247,8 @@ def _logout(desk: Desk) -> None:
     desk.pending_provider = False
     desk.held_key = None
     desk.pinned_model = None
+    desk.thesis = None
+    desk.thesis_declined = False
     if str(desk.loaded or "").startswith("universe:"):
         desk.data = None
         desk.backtest_fn = None
@@ -351,7 +368,66 @@ def _load_named(desk: Desk, verb: str, rest: str) -> None:
         say(red(str(exc)))
 
 
+def _thesis_rows(desk: Desk) -> list[dict[str, Any]] | None:
+    try:
+        rows = desk.session.theses()
+    except Exception as exc:  # noqa: BLE001 — offline or unsigned, said plainly
+        say(red(str(exc)))
+        return None
+    return [r for r in rows if isinstance(r, dict)]
+
+
+def _pin_thesis(desk: Desk, query: str) -> bool:
+    """Pin one thesis. False leaves the previous pin alone."""
+    rows = _thesis_rows(desk)
+    if rows is None:
+        return False
+    chosen, candidates = match_thesis(rows, query)
+    if chosen is None:
+        if candidates:
+            say(yellow("Which thesis? " + ", ".join(thesis_label(r) for r in candidates)))
+        else:
+            say(yellow(f"No thesis named {query!r}."))
+        return False
+    if not thesis_id_of(chosen):
+        say(yellow(f"{thesis_label(chosen)} has no id, so a run cannot be attached to it."))
+        return False
+    desk.thesis = chosen
+    desk.thesis_declined = False
+    say(dim(f"thesis {thesis_label(chosen)}"))
+    text = thesis_text(chosen)
+    if text:
+        say(dim("  " + (text if len(text) <= 240 else text[:237] + "...")))
+    return True
+
+
+def _thesis(desk: Desk, rest: str) -> None:
+    if rest.lower() in ("clear", "none", "off"):
+        desk.thesis = None
+        desk.thesis_declined = True
+        say(dim("thesis cleared"))
+        return
+    if rest:
+        _pin_thesis(desk, rest)
+        return
+    rows = _thesis_rows(desk)
+    if rows is None:
+        return
+    if not rows:
+        say(dim("No theses on this account."))
+        return
+    selected = thesis_id_of(desk.thesis) if desk.thesis else ""
+    for row in rows:
+        mark = "  selected" if selected and thesis_id_of(row) == selected else ""
+        say(f"  {thesis_label(row)}{mark}")
+    if desk.thesis is None and len(rows) > 1:
+        say(dim("Type thesis <name> to use one."))
+
+
 def _scripted(desk: Desk, name: str, flags: list[str]) -> None:
+    thesis_query, flags = pop_flag(flags, "--thesis")
+    if thesis_query and not _pin_thesis(desk, thesis_query):
+        return
     try:
         if flags:
             desk.data, desk.backtest_fn = _apply_flags(flags, desk.session, desk.data, desk.backtest_fn)
@@ -361,10 +437,14 @@ def _scripted(desk: Desk, name: str, flags: list[str]) -> None:
             say(yellow(_repl_gap(gap, name)))
             return
         grid = project_grid()
+        pinned = thesis_id_of(desk.thesis) if desk.thesis else ""
+        if desk.thesis:
+            say(dim(f"  thesis  {thesis_label(desk.thesis)}"))
         desk.last = desk.session.open(
             name,
             data=desk.data,
             backtest_fn=desk.backtest_fn,
+            thesis_id=pinned or None,
             **({"grid": grid} if grid else {}),
         )
         _drive(desk.last)
@@ -396,6 +476,7 @@ def _sentence(desk: Desk, line: str) -> None:
             except Exception as exc:  # noqa: BLE001
                 say(dim(f"  ({named} is registered and could not be loaded: {exc})"))
 
+    pinned = desk.thesis
     run = _ask(
         desk.session,
         desk.url,
@@ -403,6 +484,9 @@ def _sentence(desk: Desk, line: str) -> None:
         data=desk.data,
         backtest_fn=desk.backtest_fn,
         think=desk.think,
+        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,
     )
     if run is not None:
         desk.last = run

{alphaengine-0.9.1 → alphaengine-0.9.2}/tests/test_client.py

@@ -822,3 +822,28 @@ def test_a_rejected_trace_does_not_fail_the_run():
     assert run.trace_rejected
     assert "404" in run.trace_rejected
     assert any(path.endswith("/steps") for path, _ in session.posts)
+
+
+def test_open_attaches_a_thesis_by_id():
+    session = _TraceSession()
+    run = session.open("measure", data=[0.01, -0.01], thesis_id="th1")
+    assert run.run_id == "r1"
+    body = next(body for path, body in session.posts if path.endswith("/runs"))
+    assert body["thesis_id"] == "th1"
+    assert "statement" not in body
+
+
+def test_a_thesis_name_matches_exactly_and_does_not_guess():
+    from alphaengine.cli import match_thesis, thesis_text
+
+    rows = [
+        {"id": "a", "name": "momentum book", "summary": "pays"},
+        {"id": "b", "name": "momentum sleeve"},
+    ]
+    chosen, extra = match_thesis(rows, "momentum book")
+    assert chosen is not None and chosen["id"] == "a"
+    assert thesis_text(chosen) == "pays"
+    assert extra == []
+    chosen, extra = match_thesis(rows, "momentum")
+    assert chosen is None
+    assert {row["id"] for row in extra} == {"a", "b"}

{alphaengine-0.9.1 → alphaengine-0.9.2}/tests/test_tui.py

@@ -110,6 +110,73 @@ def test_a_scripted_run_opens_the_sharpe_line_at_full_length() -> None:
             assert "sqrt" in app.formula_text
             table = app.query_one("#series", DataTable)
             assert table.row_count == 40
+            assert any("compute.performance_report" in line for line in app.transcript)
+
+
+def test_a_thesis_is_selected_and_sent_with_the_run() -> None:
+    class _Theses(_DeskSession):
+        def _get(self, path: str):
+            if path.endswith("/theses"):
+                return {
+                    "theses": [
+                        {"id": "th1", "name": "momentum", "statement": "Large-cap momentum still pays."},
+                        {"id": "th2", "name": "quality", "statement": "Quality compounds."},
+                    ]
+                }
+            return super()._get(path)
+
+    async def body() -> None:
+        app = QuantOSApp(session=_Theses(), url="fake://", data=_returns(), keyed=True, think=_think)
+        async with app.run_test(size=(140, 42)) as pilot:
+            await pilot.pause()
+            assert "momentum" in app.transcript[-1] or any("momentum" in line for line in app.transcript)
+            assert "none" in app.rail_text
+            field = app.query_one(Input)
+            field.focus()
+            field.value = "thesis momentum"
+            await pilot.press("enter")
+            await _wait(pilot, app)
+            assert app.desk.thesis is not None
+            assert app.desk.thesis["id"] == "th1"
+            assert "momentum" in app.rail_text
+
+            field.value = "run measure"
+            await pilot.press("enter")
+            await _wait(pilot, app)
+            opens = [body for path, body in app.desk.session.posts if path.endswith("/runs")]
+            assert opens and opens[-1].get("thesis_id") == "th1"
+
+            field.value = "which of my names are overbought"
+            await pilot.press("enter")
+            await _wait(pilot, app)
+            opens = [body for path, body in app.desk.session.posts if path.endswith("/runs")]
+            assert opens[-1].get("thesis_id") == "th1"
+            assert any("thesis" in line and "momentum" in line for line in app.transcript)
+
+            field.value = "thesis clear"
+            await pilot.press("enter")
+            await _wait(pilot, app)
+            assert app.desk.thesis is None
+
+    asyncio.run(body())
+
+
+def test_one_thesis_is_pinned_at_sign_in() -> None:
+    class _One(_DeskSession):
+        def _get(self, path: str):
+            if path.endswith("/theses"):
+                return {"theses": [{"id": "th1", "name": "momentum", "summary": "It still pays."}]}
+            return super()._get(path)
+
+    async def body() -> None:
+        app = QuantOSApp(session=_One(), url="fake://", data=_returns(), keyed=True, think=_think)
+        async with app.run_test(size=(140, 42)) as pilot:
+            await pilot.pause()
+            assert app.desk.thesis is not None
+            assert app.desk.thesis["id"] == "th1"
+            assert "momentum" in app.rail_text
+
+    asyncio.run(body())
 
     asyncio.run(body())
 
@@ -214,6 +281,9 @@ def test_a_sentence_uses_the_fake_model_to_choose_a_workflow() -> None:
             field.value = "which of my names are overbought"
             await pilot.press("enter")
             await _wait(pilot, app)
-            assert any("screen_universe" in line for line in app.transcript)
+            text = "\n".join(app.transcript)
+            assert "screen_universe" in text
+            assert "the question is a screen" in text
+            assert "compute.performance_report" in text
 
     asyncio.run(body())