zeno-cli 0.3.4__py3-none-any.whl

zeno_cli/version.py

@@ -0,0 +1,67 @@
+"""CLI version + git-SHA helpers.
+
+Surfaced via `zeno --version` and `zeno version`. The version string is the
+zeno-cli pyproject.toml version (today: 0.1.0), resolved at runtime via
+importlib.metadata so a wheel install and the editable workspace agree. The
+git SHA is best-effort: if the repo is reachable via git in the working tree
+above this file, we surface a short SHA; otherwise we omit it cleanly.
+
+Used by `zeno doctor` too - the first row in the diagnostic is the version
+banner so support requests get a fingerprint.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def package_version() -> str:
+    """Return the installed zeno-cli version, or "0.0.0+unknown" on failure.
+
+    Uses ``importlib.metadata`` so an editable install (uv workspace) sees
+    the same version as a wheel install. Falls back to a sentinel string
+    when zeno-cli isn't actually installed (e.g. running from source via
+    PYTHONPATH only - the workspace test setup).
+    """
+    try:
+        from importlib.metadata import version  # noqa: PLC0415
+
+        return version("zeno-cli")
+    except Exception:
+        return "0.0.0+unknown"
+
+
+def git_sha(short: bool = True, max_depth: int = 8) -> str | None:
+    """Return the short git SHA of the working tree, or None if unavailable.
+
+    Walks up from this file looking for a .git directory so the SHA reflects
+    the source tree the CLI was launched from (important for editable
+    installs from a uv workspace). Returns None for installed wheels in
+    site-packages where there is no .git nearby.
+    """
+    here = Path(__file__).resolve()
+    for parent in [here.parent, *here.parents][:max_depth]:
+        if (parent / ".git").exists():
+            try:
+                fmt = "--short" if short else "--verify"
+                out = subprocess.run(
+                    ["git", "rev-parse", fmt, "HEAD"],
+                    capture_output=True,
+                    text=True,
+                    timeout=2,
+                    cwd=str(parent),
+                )
+                if out.returncode == 0:
+                    return out.stdout.strip() or None
+            except (OSError, subprocess.SubprocessError):
+                return None
+    return None
+
+
+def version_string() -> str:
+    """One-line version banner: '<pkg-version> (<sha>)' or '<pkg-version>'."""
+    sha = git_sha()
+    if sha:
+        return f"{package_version()} ({sha})"
+    return package_version()

zeno_cli-0.3.4.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: zeno-cli
+Version: 0.3.4
+Summary: Zeno CLI - measure the supervision cost of AI-assisted work
+Project-URL: Homepage, https://zeno.center
+Project-URL: Repository, https://github.com/Marwan01/zeno
+Author-email: Mar Helali <mar@1dev.space>
+License-Expression: Apache-2.0
+Keywords: ai,claude-code,cognitive-load,rtlx-s,session-analytics,supervision
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: alembic>=1.13.2
+Requires-Dist: keyring>=25.3.0
+Requires-Dist: matplotlib>=3.9.2
+Requires-Dist: numpy>=2.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: rich>=13.8.1
+Requires-Dist: scipy>=1.14.1
+Requires-Dist: textual>=0.86.1
+Description-Content-Type: text/markdown
+
+# zeno-cli
+
+Measure the supervision cost of AI-assisted work, from your terminal. `zeno`
+records RTLX-S load probes + session activity, fits your personal "babysitting
+tax" curve, and surfaces where your optimal number of parallel agents sits.
+
+## Install
+
+Install the `zeno` CLI straight from the monorepo over SSH. It is one
+self-contained package: the SDK, core, adapters, session-intelligence engine,
+and SQLite migrations all ship inside it. Requires **Python >= 3.12** and GitHub
+SSH access to the repo.
+
+```sh
+uv tool install \
+  --from "git+ssh://git@github.com/Marwan01/zeno.git@cli-v0.3.3#subdirectory=apps/cli" \
+  zeno-cli
+```
+
+`pipx install "git+ssh://git@github.com/Marwan01/zeno.git@cli-v0.3.3#subdirectory=apps/cli"`
+works the same way. The git clone runs an in-tree build, so the hatchling build
+hook (`apps/cli/hatch_build.py`) vendors the workspace packages into the wheel.
+**Update** by bumping the tag: re-run with `@cli-v0.3.3` (uv) or
+`pipx install --force ...@<newtag>`.
+
+**Why git+ssh and not an index:** TestPyPI is not a durable distribution channel
+and a private index is overkill at team scale. A public PyPI wheel comes only
+when non-repo-access users do. The packaging blocker for it is now resolved - the
+build is sdist-clean (`uv build --sdist` -> a wheel built from that sdist installs
+and runs every verb; see the build-hook note under [Packaging](#packaging-notes)),
+so the remaining gate is purely "do public users exist yet", not a broken build.
+
+### Install channels (staged)
+
+The distribution channel widens as the audience does. Use the one that matches
+where the project is, not the most convenient:
+
+| Stage | Channel | Command | Status |
+| :--- | :--- | :--- | :--- |
+| Now | git+ssh tag | `uv tool install --from "git+ssh://git@github.com/Marwan01/zeno.git@cli-v0.3.3#subdirectory=apps/cli" zeno-cli` | Live (needs repo SSH access) |
+| Next | PyPI | `uv tool install zeno-cli` (or `pipx install zeno-cli`) | Lands when `.github/workflows/publish.yml` runs on the first GitHub release; the packaging metadata is ready |
+| Later | Homebrew | `brew install zeno-cli` | Formula not written yet |
+
+The PyPI publish is OIDC Trusted-Publishing gated and fires only on a published
+GitHub release - see `.github/workflows/publish.yml`. Until that first release,
+the git+ssh tag is the supported path.
+
+**From a built wheel** (offline / air-gapped; the wheel is fully self-contained):
+
+```sh
+uv build --wheel --package zeno-cli          # -> dist/zeno_cli-*.whl
+uv tool install ./dist/zeno_cli-0.3.3-py3-none-any.whl
+```
+
+**From source** (development inside the monorepo, no install):
+
+```sh
+uv run --project /path/to/zeno zeno <cmd>
+```
+
+New here? Follow `docs/ADOPT.md` for the 10-minute install -> capture -> survey loop.
+
+## Use
+
+```sh
+zeno survey        # log how a session felt (~6s, RTLX-S 5-item probe)
+zeno status        # tier, streak, tax curve, cognitive state, today's survey
+zeno curve         # render the babysitting-tax curve (needs ~10 sessions of data)
+zeno weekly        # 7-day rollup
+zeno doctor        # health check: API reachability + identity
+zeno login         # browser sign-in; stores a Clerk JWT in the OS keyring
+zeno whoami        # show the identity + tier the API sees for your token
+zeno logout        # clear the stored token
+```
+
+### Authentication
+
+`zeno login` runs a browser + loopback sign-in and stores the resulting Clerk
+JWT in your OS keyring; the CLI sends it as a `Bearer` token so the API
+attributes requests to your user. Token resolution order, used by every
+command: `ZENO_API_TOKEN` env override first, then the keyring token from
+`zeno login`, then none (local-only). Use `zeno login --no-browser` for SSH /
+headless (prints the URL), and `--authorize-url` / `ZENO_LOGIN_AUTHORIZE_URL`
+to target a non-default bridge.
+
+> The dashboard `/cli/authorize` bridge page + the Clerk `zeno-api` JWT template
+> that mint the token are a documented follow-up (not yet shipped). See
+> `src/zeno_cli/login.py` for the callback contract.
+
+Full daily-loop guide: `docs/CLI_QUICKSTART.md`. Requires Python >= 3.12.
+
+## Cognition HUD add-on
+
+`zeno-hud-bar` is the single differentiated cognition line (`att / eff / drv`) that
+stacks UNDER whatever popular HUD you already run, instead of replacing it. Claude Code
+has one statusLine slot, so zeno rides the HUD you have:
+
+```sh
+zeno hud install            # auto-detect: ccstatusline (native widget) or claude-hud (wrapper)
+zeno hud install --dry-run  # print what would change, write nothing
+zeno hud status             # what is detected + whether the line is wired in
+zeno hud uninstall          # remove from both adapters (idempotent; --restore for byte-for-byte)
+```
+
+`--target {auto,ccstatusline,claude-hud}` forces an adapter (auto prefers ccstatusline
+when both are present). Every edit is backed up and reversible. The bar is crash-safe: on
+any error it prints an empty line and exits 0, so it never breaks the host HUD. Full model
+and both recipes: `docs/HUD_ADDON.md`.
+
+## Packaging notes
+
+- **sdist-clean via a build hook.** `apps/cli/hatch_build.py` (a custom hatchling
+  build hook, enabled on BOTH the `wheel` and `sdist` targets) vendors the four
+  workspace packages (`zeno_core` / `zeno_sdk` / `zeno_adapters` /
+  `zeno_session_intel`) plus the SDK alembic tree into an in-root, gitignored
+  `_vendor_build/` stage at build time. The wheel target flattens them to the
+  archive top level (the exact layout the old static `force-include` produced, so
+  absolute imports resolve unchanged); the sdist target ships the whole
+  `_vendor_build/` stage inside the tarball so a wheel built FROM the sdist finds
+  the sources locally. This replaced the static `[tool.hatch...force-include]` of
+  `../../packages/...` relative-parent paths, whose `..` escaped the sdist root and
+  were silently dropped - a wheel from that sdist died with "Forced include not
+  found". Repo source under `packages/*` is never moved, so the uv workspace, the
+  API, and the test suite keep importing the editable members unchanged; the
+  vendored copy is purely a build artifact.
+- `zeno ingest` / `zeno usage` are backed by `zeno_session_intel`, vendored
+  alongside the other internal packages by the build hook. It is stdlib-only with
+  relative-only internal imports, so it flattens into the wheel with zero import
+  rewrites. Omit it and both subcommands abort with a "not bundled" hint at runtime
+  (the regression fixed in 0.3.3); `scripts/install-smoke.sh` now exercises every
+  advertised subcommand so this cannot ship silently again.
+- Agent-framework adapters (`zeno_sdk.adapters` -> crewai / openai / anthropic /
+  langgraph) are off the CLI path and pull heavy framework deps; they are kept
+  optional and will be exposed as extras (e.g. `zeno-cli[crewai]`) in a later stage.

zeno_cli-0.3.4.dist-info/RECORD

@@ -0,0 +1,69 @@
+zeno_cli/__init__.py,sha256=k_rgP6JpTT711x3-8Pss91qDM-W8iE212qb98h8yL8w,36
+zeno_cli/doctor.py,sha256=2fYpTBiZRT7Oxmc0vJs5N_nxRXfPwDUsmRs5GE6oQpY,21565
+zeno_cli/hook_install.py,sha256=2T_R-cpe_TdjJMjjye4IFr4G1I0GldIgxCoCQqL5Te4,9679
+zeno_cli/interview_invites.py,sha256=7c9PhjTNsRdhvsK-dibEtfH-SIgIgDemJyAzZ0wdFSU,12276
+zeno_cli/login.py,sha256=0TrlNlumx4vTDxNdREE1FjEJPevZRTZVvBUMmIcyjVU,9727
+zeno_cli/main.py,sha256=jexg-7f0IHEhwZMHuNaxeGSZivJvTfC-2Npip5s_UeY,94823
+zeno_cli/onboard.py,sha256=3c8NwAvuaFf_uDBgnwvLPKgPoh2kKg3xO74fEJR9YYs,8505
+zeno_cli/outreach.py,sha256=GJo1FeMhZQ2yhlZ10qKC0aNNAz2AC7DDfcQ-Eke9DuE,15691
+zeno_cli/version.py,sha256=n8mZkywYtXEOSR2YnohJ3gLJ_hcxLgPU6F5Oj_2jFgo,2459
+zeno_cli/_hooks/cc_bridge.py,sha256=EgOszKaREn1T0x0SfR1LRCMB32xa5jD144UebAlT8ZQ,40531
+zeno_cli/hud/__init__.py,sha256=leofDy-tpR_QI7fLtKtHt3afDR3uGtOM_0YIWJjEdnA,81
+zeno_cli/hud/hud_install.py,sha256=vWGa0CGsgMzasSW6WYvfP4IrF5P9Rku9qlb7esX8Vbk,25519
+zeno_cli/hud/zeno_attention.py,sha256=vg-_UIAkAiNLd32JfLlQo_4-5yMsEDdMPd8eSauDI_E,11216
+zeno_cli/hud/zeno_cognition.py,sha256=WuFCMH8RVLQegQlnqcjBoijqKeZ5uym35h-tX3fSMEM,18505
+zeno_cli/hud/zeno_hud.py,sha256=J9oxTIsua8p6qfusjlyGO8ly_WinUnpp4rWPGaqL-34,20301
+zeno_adapters/__init__.py,sha256=KQT3Gf4ihdqsIOPBo5jaZeamv8pC3xim0wr_7Z7SZz8,575
+zeno_adapters/_common.py,sha256=s9Vlr0yZDIAka8xiy947UNxnmBjU-XbyWdLzx6FCG18,1165
+zeno_adapters/anthropic.py,sha256=lAOfpnGzKbzn5MLDULDVWXxy_VwIx8YYYpBa4rHAMDo,2373
+zeno_adapters/claude_code.py,sha256=o0xlv3lxA6caiOZTrRZVbUlpDHzLBDKzE-mBWvlctYQ,3086
+zeno_adapters/crewai.py,sha256=YHVNg0vE9v8JEUP0H3-bhpkj_fVnqqBbqD1AaDiomYc,3413
+zeno_adapters/langgraph.py,sha256=TzTgCG5iGhAa_wIMJ9XEllvfgyUvplOVT46MnCjQchE,1806
+zeno_adapters/openai.py,sha256=mGIwkqgNiIhMrPeQ2fJRL-chj55RyrxTSobBC3yUKbA,3607
+zeno_core/__init__.py,sha256=nPS4Sc_J6RVCHkaLtschKWi0DokrKS4zUW1K_gEJAcI,1510
+zeno_core/analytics.py,sha256=GV44S1YjDrON3kU6OwshSRONSQTEVcWkijrgD1AALjw,6595
+zeno_core/rtlx_s.py,sha256=TQABm29VCLDxSbzQRq4bKmlPqSysYHQniw85klItHOM,19217
+zeno_core/streak.py,sha256=lQKHL4jXr53LrWebRqR1C2mfsrlacaV4qJfP15b-XeE,6826
+zeno_core/tlx_s.py,sha256=uCBRFaMMwEFNpmbUY00EOWYEf-4-_toitv80AiZNB9o,6154
+zeno_sdk/__init__.py,sha256=zpIpXr9s0JrctbykFiEBxFSQZMdRQvpopAUt-c2Cngw,127
+zeno_sdk/_runtime.py,sha256=HaIO3tlu1bXJNfYB10KubuDtQoWhUZTEhH_uyhQMM18,348
+zeno_sdk/auth.py,sha256=5uvKCeMSslAGI7jcdVHGq8bjMwwV_kW18LvcoQ1f94I,499
+zeno_sdk/client.py,sha256=WNmBygABgeZSo01anqbTkh4CygUX3s4fbl-99TuMTXQ,2759
+zeno_sdk/config.py,sha256=ERnRdgqyl2o7OXJm5tV3YymTHkiR0Q8yTyUrTX_fD_c,1908
+zeno_sdk/daemon.py,sha256=FdY-_df9vRM54uKGcdKYCXUabUmSNs4AH0f0MTEDTXw,2258
+zeno_sdk/privacy.py,sha256=P4OuxwgfMOVvZfEkTAP15GZm5156wTM3vNO-l8P8tZI,1374
+zeno_sdk/session.py,sha256=aQ6G9fOnnLtDLzGGyqu_2mgHO7JBieseY8TyCbSlpJo,6100
+zeno_sdk/storage.py,sha256=3wf2ED8TeTNIrnQmQlJRTXIgLDVcp266grcaVOVEH4o,19076
+zeno_sdk/_generated/__init__.py,sha256=LyDCZa0IW5FIpGsSH8j9owFzuVepSgycbx47T4w-5QQ,96
+zeno_sdk/_generated/client.py,sha256=5Abp7n_ST0AsPwsY6BVUhOgkZib3sRnFWfwSmgkp0pc,26729
+zeno_sdk/_migrations/alembic.ini,sha256=0gpaG_bxrMvXtPuM9eUlEbl6mD0BqwvglNZ52PxL-O4,526
+zeno_sdk/_migrations/alembic/env.py,sha256=iz-0Ta1jTqgiZa42zczrrHWZgucF8I6TlKOiaqUB2LU,866
+zeno_sdk/_migrations/alembic/script.py.mako,sha256=Jc9jK0i7Tb0UW4FKhYeffle1wcBwJklOJ0hO3EYyyUY,325
+zeno_sdk/_migrations/alembic/versions/0001_initial.py,sha256=jw7WHmoPTWSu-nWj5xyU4nIJsdIywkGww4-NSPtYK90,3061
+zeno_sdk/_migrations/alembic/versions/0002_cognition_samples.py,sha256=aOd76chDv36T9N4slvESE_TrHdCC5oMQjzqH67x2yF4,2151
+zeno_sdk/_migrations/alembic/versions/0003_cognition_drivers.py,sha256=OqLzyFX3ri2BrL9kE8ZXaNtD5nqxqtURaHNmYPG93Ig,1198
+zeno_sdk/_migrations/alembic/versions/0004_transcript_intelligence.py,sha256=vMkWSGI-WpZYV5nMioQW1rAnVgUdxVrnYg5kyCr0QNM,12724
+zeno_sdk/adapters/__init__.py,sha256=qF1-El8YWrdQjYJpOyvOcZa3FdwoCvRGYQWyRjk71Bk,543
+zeno_sdk/adapters/anthropic.py,sha256=OMZ8-UEXIHH5KoD9SKcQNX2B66oJU6M5KZGz9d90e7I,109
+zeno_sdk/adapters/claude_code.py,sha256=gvXAJiS4q9bixsz33SMhFKASw1vVAOVQcAUUY8lkKE4,111
+zeno_sdk/adapters/crewai.py,sha256=yeR5ihDZYrXfjw5Bg8fG_3QTHjQwE_0NDayELBHqAPo,154
+zeno_sdk/adapters/langgraph.py,sha256=zWbVzdkU3zdkJwEqOzj1H652ECXNq0gRC_aSLFM0EXg,109
+zeno_sdk/adapters/openai.py,sha256=EwIyTBTFtXOxuHbA31WNkMoQV4jdqukb8XMlpz-UiVg,106
+zeno_sdk/types/__init__.py,sha256=knlgMTaeZ4gDBLpuAC4_mFvQ_oFktO9co9-XhfX1emQ,3267
+zeno_session_intel/__init__.py,sha256=hPlu9-Qwxe2hlevZW6kQs_pgEzJqZWspXNNHy7zNt_8,880
+zeno_session_intel/analytics.py,sha256=gw68B-h9nO7nkmg5VO3ue00Giqhq4vskJCP5D6DkNH4,21639
+zeno_session_intel/compression.py,sha256=3q1NklgUrhC2K47dNmydqvGnnn59KRbwQBSnvdyCM6g,5066
+zeno_session_intel/ingest.py,sha256=KAdoxK6yZnOicYrFFQxJR5O1ONd9kH1OOBPdQi2cPgg,15030
+zeno_session_intel/model.py,sha256=jP2cocAVjl_MlBI0bralV_TFUkalo-PRP480aLjH9FY,4235
+zeno_session_intel/prices.py,sha256=uMxVYL6N4HqK1_usJuEeXWtlDkmZ_wMRtF6yNiC67Bw,9905
+zeno_session_intel/schema.py,sha256=VTmUWvSXB7zgH_zZpnEFdjqJ2fIQ1pQds3OX0oKMTXo,12376
+zeno_session_intel/signals.py,sha256=JrInX4_QiOhPQfrky_OMHwjdb_lip-w44h-E_Xua1bg,11539
+zeno_session_intel/taxonomy.py,sha256=u_9COlFHeI3sMg0Nqd_kg2sFfDjdQwx6R-OW0vA7iCQ,2107
+zeno_session_intel/parsers/__init__.py,sha256=rEzx44_To5fZ4IeblMio7Dxx29w9vAEn6YjRTWEf9yM,1323
+zeno_session_intel/parsers/claude_code.py,sha256=SeiT9jrolIsCvSxXUlb4fUWzHEWLekqA4-b6MY4hXH0,6405
+zeno_session_intel/parsers/codex.py,sha256=5qn28QItZMiiDY9OvjfuRrgNfUozpcThQngZqueVqp8,10220
+zeno_session_intel/parsers/cursor.py,sha256=DX1DZHlu1DxzWTGrDnVc4GMf52KdV8MtlwbO_ryix34,7352
+zeno_cli-0.3.4.dist-info/METADATA,sha256=OIBlzm7x6cizBQ37C3tfrwYOUO2SGcMwKWg63wF190g,7792
+zeno_cli-0.3.4.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+zeno_cli-0.3.4.dist-info/entry_points.txt,sha256=e4KAP7N_td8T76VwMcY_Ey0eCz2L8zAO_mpeUKr7CAQ,128
+zeno_cli-0.3.4.dist-info/RECORD,,

zeno_cli-0.3.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

zeno_cli-0.3.4.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+zeno = zeno_cli.main:main
+zeno-hud = zeno_cli.hud.zeno_hud:main
+zeno-hud-bar = zeno_cli.hud.zeno_hud:bar_main

zeno_core/__init__.py

@@ -0,0 +1,67 @@
+"""Core analytics package."""
+
+from .analytics import (
+    CurveResult,
+    SessionPoint,
+    fit_babysitting_tax_curve,
+    render_curve_ascii,
+    render_weekly_table,
+    save_curve_png,
+    weekly_summary,
+)
+from .rtlx_s import (
+    RTLXS_ITEMS,
+    RTLXS_SCHEMA_VERSION,
+    RTLXResponse,
+    load_last_defaults,
+    run_rtlxs_survey_tui,
+    save_last_defaults,
+    validate_item_keys,
+)
+from .streak import (
+    DAY_CUTOFF_HOUR,
+    StreakResult,
+    compute_streak,
+    has_logged_today,
+    read_streak_from_local_storage,
+)
+from .tlx_s import (
+    SUBSCALES,
+    TLXSurveyResult,
+    compute_babysitting_tax_index,
+    compute_composite_load,
+    run_tlx_survey_tui,
+    should_prompt_probe,
+    validate_item_wording,
+)
+
+__all__ = [
+    "SUBSCALES",
+    "TLXSurveyResult",
+    "CurveResult",
+    "SessionPoint",
+    "fit_babysitting_tax_curve",
+    "render_curve_ascii",
+    "render_weekly_table",
+    "save_curve_png",
+    "weekly_summary",
+    "compute_babysitting_tax_index",
+    "compute_composite_load",
+    "run_tlx_survey_tui",
+    "should_prompt_probe",
+    "validate_item_wording",
+    # RTLX-S (research 1, 2026-06-07 PM3)
+    "RTLXS_ITEMS",
+    "RTLXS_SCHEMA_VERSION",
+    "RTLXResponse",
+    "load_last_defaults",
+    "run_rtlxs_survey_tui",
+    "save_last_defaults",
+    "validate_item_keys",
+    # Streak tracker (research 1 PM3 follow-up, 2026-06-07)
+    "DAY_CUTOFF_HOUR",
+    "StreakResult",
+    "compute_streak",
+    "has_logged_today",
+    "read_streak_from_local_storage",
+]

zeno_core/analytics.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Resolves the np.ndarray annotations below for type-checkers / ruff
+    # WITHOUT a runtime import (these names are strings under
+    # `from __future__ import annotations`).
+    import numpy as np
+
+# numpy / scipy / matplotlib (and rich) are imported lazily INSIDE the functions
+# that use them, not at module top. Importing zeno_core.analytics used to pull
+# the full scientific stack (~185ms: matplotlib.pyplot alone ~70ms, plus numpy
+# and scipy), which every `zeno --version` / `status` / `tips` paid even though
+# those paths never fit or plot a curve. Deferring keeps the hot path cheap;
+# the libs load once, on first call, and are cached in sys.modules thereafter.
+# (`from __future__ import annotations` makes the np.ndarray signatures below
+# strings, so they do not trigger an import at definition time.)
+
+
+@dataclass(slots=True)
+class SessionPoint:
+    session_id: str
+    n_agents_active: float
+    composite_load: float
+    output_quality: float | None
+    ended_at: datetime | None = None
+
+
+@dataclass(slots=True)
+class CurveResult:
+    xs: list[float]
+    composite_curve: list[float]
+    quality_curve: list[float]
+    optimal_n_agents: int | None
+    calibration_in_progress: bool
+
+
+def trim_outliers(points: list[SessionPoint]) -> list[SessionPoint]:
+    if len(points) < 20:
+        return points
+
+    import numpy as np
+
+    loads = np.array([point.composite_load for point in points], dtype=float)
+    low, high = np.percentile(loads, [5, 95])
+    filtered = [point for point in points if low <= point.composite_load <= high]
+    return filtered
+
+
+def _tricube(distance: np.ndarray) -> np.ndarray:
+    import numpy as np
+
+    clipped = np.clip(1 - np.power(np.abs(distance), 3), 0, None)
+    return np.power(clipped, 3)
+
+
+def lowess_smooth(xs: np.ndarray, ys: np.ndarray, bandwidth: float) -> np.ndarray:
+    import numpy as np
+    from scipy import linalg
+
+    n = len(xs)
+    if n == 0:
+        return np.array([])
+    if n == 1:
+        return ys.copy()
+
+    span = max(2, int(math.ceil(bandwidth * n)))
+    smoothed = np.zeros(n, dtype=float)
+    x_design = np.column_stack((np.ones(n), xs))
+
+    for index, x0 in enumerate(xs):
+        distances = np.abs(xs - x0)
+        h = np.partition(distances, min(span - 1, n - 1))[min(span - 1, n - 1)]
+        if h == 0:
+            weights = np.where(distances == 0, 1.0, 0.0)
+        else:
+            weights = _tricube(distances / h)
+        sqrt_w = np.sqrt(weights)
+        wx = x_design * sqrt_w[:, None]
+        wy = ys * sqrt_w
+        beta, *_ = linalg.lstsq(wx, wy)
+        smoothed[index] = beta[0] + beta[1] * x0
+    return smoothed
+
+
+def fit_babysitting_tax_curve(points: list[SessionPoint]) -> CurveResult:
+    import numpy as np
+
+    filtered = trim_outliers(points)
+    if len(filtered) < 10:
+        return CurveResult([], [], [], None, calibration_in_progress=True)
+
+    bandwidth = 0.5 if len(filtered) < 50 else 0.3
+    sorted_points = sorted(filtered, key=lambda point: point.n_agents_active)
+    xs = np.array([point.n_agents_active for point in sorted_points], dtype=float)
+    composite = np.array([point.composite_load for point in sorted_points], dtype=float)
+    quality_values = np.array(
+        [
+            point.output_quality if point.output_quality is not None else 0.0
+            for point in sorted_points
+        ],
+        dtype=float,
+    )
+
+    composite_curve = lowess_smooth(xs, composite, bandwidth)
+    quality_curve = lowess_smooth(xs, quality_values, bandwidth)
+
+    max_index = int(np.argmax(quality_curve))
+    optimal = int(round(xs[max_index])) if len(xs) else None
+    return CurveResult(
+        xs=xs.tolist(),
+        composite_curve=composite_curve.tolist(),
+        quality_curve=quality_curve.tolist(),
+        optimal_n_agents=optimal,
+        calibration_in_progress=False,
+    )
+
+
+def render_curve_ascii(curve: CurveResult) -> str:
+    if curve.calibration_in_progress:
+        return "Calibration in progress: need at least 10 sessions."
+    if not curve.xs:
+        return "No curve data available."
+
+    import numpy as np
+
+    chars = "▁▂▃▄▅▆▇█"
+    values = np.array(curve.quality_curve, dtype=float)
+    if np.allclose(values.max(), values.min()):
+        sparkline = chars[0] * len(values)
+    else:
+        scaled = (values - values.min()) / (values.max() - values.min())
+        sparkline = "".join(chars[int(round(item * (len(chars) - 1)))] for item in scaled)
+    return f"Quality curve: {sparkline}"
+
+
+def save_curve_png(curve: CurveResult, output_path: Path) -> None:
+    import matplotlib
+
+    matplotlib.use("Agg")
+    from matplotlib import pyplot as plt
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    plt.figure(figsize=(8, 4))
+    plt.plot(curve.xs, curve.composite_curve, label="Composite Load", color="#7a1f2f")
+    plt.plot(curve.xs, curve.quality_curve, label="Output Quality", color="#1f4f7a")
+    plt.xlabel("n_agents_active")
+    plt.ylabel("score")
+    plt.title("Babysitting Tax Curve")
+    plt.legend()
+    plt.tight_layout()
+    plt.savefig(output_path)
+    plt.close()
+
+
+def weekly_summary(points: list[SessionPoint], *, now: datetime | None = None) -> dict[str, float]:
+    if not points:
+        return {"sessions": 0, "avg_composite_load": 0.0, "avg_quality": 0.0}
+
+    import numpy as np
+
+    now = now or datetime.now(tz=UTC)
+    week_ago = now - timedelta(days=7)
+    recent = [point for point in points if point.ended_at and point.ended_at >= week_ago]
+    if not recent:
+        return {"sessions": 0, "avg_composite_load": 0.0, "avg_quality": 0.0}
+    loads = [point.composite_load for point in recent]
+    quality = [point.output_quality or 0.0 for point in recent]
+    return {
+        "sessions": float(len(recent)),
+        "avg_composite_load": float(np.mean(loads)),
+        "avg_quality": float(np.mean(quality)),
+    }
+
+
+def render_weekly_table(summary: dict[str, float]) -> str:
+    from rich.console import Console
+    from rich.table import Table
+
+    console = Console(record=True)
+    table = Table(title="Weekly Babysitting Summary")
+    table.add_column("Metric")
+    table.add_column("Value")
+    table.add_row("Sessions", str(int(summary["sessions"])))
+    table.add_row("Avg Composite Load", f"{summary['avg_composite_load']:.2f}")
+    table.add_row("Avg Output Quality", f"{summary['avg_quality']:.2f}")
+    console.print(table)
+    return console.export_text()