alphaengine 0.9.0__tar.gz → 0.9.2__tar.gz

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

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

@@ -76,4 +76,12 @@ is what a changed figure costs. The API may still move underneath it.
 # Close fills are unchanged. No golden in tests/test_goldens.py moves. The
 # same release makes the full-screen terminal the only session, and posts each
 # math line's series on `/traces` without putting those series inside figures.
-__version__ = "0.9.0"
+#
+# 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.
+#
+# 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → alphaengine-0.9.2}/src/alphaengine/core/risk.py

@@ -129,7 +129,12 @@ def compute_var_cvar(
     record(
         "parametric_var",
         "z * std(r, ddof=1) * sqrt(horizon), z = normsinv(confidence), as a positive percent",
-        inputs={"n_obs": int(n_obs), "confidence": confidence, "horizon_days": int(horizon_days), "z": round(z, 6)},
+        inputs={
+            "n_obs": int(n_obs),
+            "confidence": confidence,
+            "horizon_days": int(horizon_days),
+            "z": round(z, 6),
+        },
         series={"returns": arr},
         result=result["parametric"]["var_pct"],
     )

{alphaengine-0.9.0 → alphaengine-0.9.2}/src/alphaengine/model.py

@@ -328,13 +328,12 @@ def build_think(
         )
 
     raise NoModelConfigured(
-        "No model key found. The agentic path runs under YOUR account, so it "
-        "needs your key in this shell:\n"
-        "    ANTHROPIC_API_KEY=...   or   OPENAI_API_KEY=...\n"
-        "    or GEMINI_API_KEY / GROQ_API_KEY / OPENROUTER_API_KEY /\n"
-        "    AZURE_OPENAI_API_KEY / ALPHAENGINE_API_KEY+ALPHAENGINE_BASE_URL\n"
-        "Nothing here stores it, and the scripted path (`run <workflow>`) needs "
-        "no model at all."
+        "No model key found. In the session, type `enter model key` and paste it.\n"
+        "Or set the key in this shell: ANTHROPIC_API_KEY, OPENAI_API_KEY, "
+        "GEMINI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, "
+        "AZURE_OPENAI_API_KEY, or ALPHAENGINE_API_KEY with ALPHAENGINE_BASE_URL.\n"
+        "Nothing here sends that key to QuantOS, and the scripted path "
+        "(`run <workflow>`) needs no model at all."
     )