enano 0.2.0__tar.gz

enano-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.DS_Store

enano-0.2.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: enano
+Version: 0.2.0
+Summary: Elevation models for personal goals and pitch decks: pull versioned bundles, scan documents deterministically, entirely on your machine.
+License: Proprietary
+Keywords: cli,deterministic,goals,habits,pitch-decks
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Provides-Extra: semantic
+Requires-Dist: onnxruntime; extra == 'semantic'
+Description-Content-Type: text/markdown
+
+# enano: Explorable nano models for your second brain
+
+28,000+ pieces of advice distilled from key books on the topics of personal goals, career advice and startup pitch decks.
+
+Each model package comes with an ONNX model, JSON source attributes, excerpts, custom advice, regex detectors, a vector index, and neural scoring engine.
+
+Use cli tools to explore your own .md and .txt files via command or use Claude Cowork, OpenAI Chat GPT directly with the JSON fies and Python scripts.
+
+**WEB APP & DEMO**
+https://enano.ai
+Web app is private and runs entirely in frontend, no user data or text is sent, models designed to run entirely in-browser.
+<p align="center">
+  <a href="docs/screens/screen-1.png"><img src="docs/screens/screen-1.jpg" width="49%"></a>
+  <a href="docs/screens/screen-2.png"><img src="docs/screens/screen-2.jpg" width="49%"></a>
+</p>
+
+## Install
+
+```bash
+pipx install enano
+```
+
+## Quickstart
+
+```bash
+enano scan                   # checks .md in the folder against the  default model
+```
+
+| Model | Default | Sources | Corpus | Rules | Detectors | Advice | Pull |
+|---|---|---|---|---|---|---|---|
+| **personal-goals** | yes | 21 | 2.3 GB | 15,833 | 31 | 391 | 35.8 MB |
+| **career-advice** | | 5 | 91 MB | 5,026 | 142 | 1,877 | 25 MB |
+| **pitch-decks** | | 5 | 2.2 GB | 75 | 75 | 1,132 | 22.5 MB |
+
+
+## Usage
+You can use the packages via the cli toos OR you can use with Claude Cowork et. al.
+
+```bash
+enano pull personal-goals         # fetch the personal-goals bundle (~36 MB, sha-verified)
+enano scan notes.md               # scan a document (regex plus the optional neural pass)
+enano scan                        # every .md in the current folder (stdin when piped)
+enano walk                        # every .md in every subfolder
+enano elevators                   # list the source works with their counts
+enano elevations "fear of failure"  # search the rule corpus, any word or phrase
+enano list                        # every model you can pull
+enano models                      # what's installed
+enano use pitch-decks             # switch the default model
+enano update                      # check for newer bundles
+enano upgrade                     # fetch newer bundles
+enano doctor                      # environment and store diagnostics
+```
+
+**Global Parameters**
+Every command takes `--json`; there are no other flags to learn. Bare `enano`
+onboards: it pulls the default model and shows the shortest path to a first scan.
+
+## Contact
+
+Found a bug or have a question? [Open an issue](https://github.com/enano-ai/enano/issues)
+or visit [enano.ai](https://enano.ai).

enano-0.2.0/README.md

@@ -0,0 +1,61 @@
+# enano: Explorable nano models for your second brain
+
+28,000+ pieces of advice distilled from key books on the topics of personal goals, career advice and startup pitch decks.
+
+Each model package comes with an ONNX model, JSON source attributes, excerpts, custom advice, regex detectors, a vector index, and neural scoring engine.
+
+Use cli tools to explore your own .md and .txt files via command or use Claude Cowork, OpenAI Chat GPT directly with the JSON fies and Python scripts.
+
+**WEB APP & DEMO**
+https://enano.ai
+Web app is private and runs entirely in frontend, no user data or text is sent, models designed to run entirely in-browser.
+<p align="center">
+  <a href="docs/screens/screen-1.png"><img src="docs/screens/screen-1.jpg" width="49%"></a>
+  <a href="docs/screens/screen-2.png"><img src="docs/screens/screen-2.jpg" width="49%"></a>
+</p>
+
+## Install
+
+```bash
+pipx install enano
+```
+
+## Quickstart
+
+```bash
+enano scan                   # checks .md in the folder against the  default model
+```
+
+| Model | Default | Sources | Corpus | Rules | Detectors | Advice | Pull |
+|---|---|---|---|---|---|---|---|
+| **personal-goals** | yes | 21 | 2.3 GB | 15,833 | 31 | 391 | 35.8 MB |
+| **career-advice** | | 5 | 91 MB | 5,026 | 142 | 1,877 | 25 MB |
+| **pitch-decks** | | 5 | 2.2 GB | 75 | 75 | 1,132 | 22.5 MB |
+
+
+## Usage
+You can use the packages via the cli toos OR you can use with Claude Cowork et. al.
+
+```bash
+enano pull personal-goals         # fetch the personal-goals bundle (~36 MB, sha-verified)
+enano scan notes.md               # scan a document (regex plus the optional neural pass)
+enano scan                        # every .md in the current folder (stdin when piped)
+enano walk                        # every .md in every subfolder
+enano elevators                   # list the source works with their counts
+enano elevations "fear of failure"  # search the rule corpus, any word or phrase
+enano list                        # every model you can pull
+enano models                      # what's installed
+enano use pitch-decks             # switch the default model
+enano update                      # check for newer bundles
+enano upgrade                     # fetch newer bundles
+enano doctor                      # environment and store diagnostics
+```
+
+**Global Parameters**
+Every command takes `--json`; there are no other flags to learn. Bare `enano`
+onboards: it pulls the default model and shows the shortest path to a first scan.
+
+## Contact
+
+Found a bug or have a question? [Open an issue](https://github.com/enano-ai/enano/issues)
+or visit [enano.ai](https://enano.ai).

enano-0.2.0/enano/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("enano")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev0"

enano-0.2.0/enano/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

enano-0.2.0/enano/cli.py

@@ -0,0 +1,595 @@
+"""The enano CLI: pull-based bundle management plus a front door to the
+bundle's own deterministic scan tools."""
+
+from __future__ import annotations
+
+import argparse
+import json as jsonlib
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from . import __version__
+from . import registry as reg
+from . import store
+
+
+def _parse_selector(selector: str) -> tuple[str, str | None]:
+    model, _, version = selector.partition("@")
+    return model.strip(), (version.strip() or None) if version else None
+
+
+def _require_bundle(selector: str, auto_pull: bool, quiet: bool = False) -> Path:
+    model, version = _parse_selector(selector)
+    path = store.resolve_version(model, version)
+    if path:
+        return path
+    entry = reg.resolve_entry(reg.fetch_registry(refresh=True), model, version)
+    size_mb = round(entry["bytes"] / 1e6, 1)
+    if not auto_pull:
+        print(f"{model} is not installed locally. Run: enano pull {model}  ({size_mb} MB)")
+        raise SystemExit(2)
+    prompt = f"{model}@{entry['version']} is not installed — download it now ({size_mb} MB)? [y/N] "
+    if sys.stdin.isatty() and input(prompt).strip().lower() not in ("y", "yes"):
+        raise SystemExit(2)
+    if not quiet:
+        print(f"pulling {model}@{entry['version']} …")
+    _pull(model, entry)
+    path = store.resolve_version(model, version)
+    if not path:
+        raise SystemExit(f"pull finished but {selector} still not resolvable")
+    return path
+
+
+def _run_tool(bundle: Path, tool: str, forward: list[str]) -> int:
+    tool_path = bundle / "tools" / f"{tool}.py"
+    if not tool_path.is_file():
+        runnable = (bundle / "tools" / "scan.py").is_file()
+        hint = "" if runnable else " (this bundle ships no scanner — weights/corpus only)"
+        raise SystemExit(f"tool '{tool}' not found in {bundle.name}{hint}")
+    return subprocess.call([sys.executable, str(tool_path), *forward], cwd=str(bundle))
+
+
+def _pull(model: str, entry: dict, quiet: bool = False) -> Path:
+    archive = reg.download_archive(
+        entry.get("url") or entry["mirrorUrl"],
+        entry.get("bytes", 0),
+        entry["sha256"],
+        store.store_root() / "archives",
+    )
+    target = store.install_bundle(model, entry["version"], archive)
+    if not quiet:
+        print(f"installed {model}@{entry['version']} -> {target}")
+    return target
+
+
+# ------------------------------------------------------------- subcommands
+
+
+def cmd_pull(args: argparse.Namespace) -> int:
+    registry = reg.fetch_registry(refresh=True)
+    selectors = list(args.selectors or [])
+    if selectors == ["all"]:
+        selectors = sorted(reg.registry_models(registry))
+    if not selectors:
+        raise SystemExit("nothing to pull: give a model (or: enano pull all)")
+    results = []
+    for selector in selectors:
+        model, version = _parse_selector(selector)
+        entry = reg.resolve_entry(registry, model, version)
+        if store.model_dir(model, entry["version"]).is_dir():
+            if not args.json:
+                print(f"{model}@{entry['version']} already installed")
+            results.append({"model": model, "version": entry["version"], "status": "already-installed"})
+            continue
+        _pull(model, entry, quiet=args.json)
+        results.append({"model": model, "version": entry["version"], "status": "installed"})
+    if args.json:
+        print(jsonlib.dumps(results, indent=2))
+    return 0
+
+
+def _human_bytes(size: float) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1000:
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1000
+    return f"{size:.1f} TB"
+
+
+def _clip(text: str, width: int) -> str:
+    return text if len(text) <= width else text[: width - 1].rstrip() + "…"
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """Remote: the registry catalog — one row per model at latest."""
+    registry = reg.fetch_registry(refresh=True)
+    models = reg.registry_models(registry)
+    if not models:
+        raise SystemExit("registry has no models published")
+    rows = []
+    for name in sorted(models):
+        entry = models[name]
+        version = entry.get("latest") or sorted(entry.get("versions", {}))[-1]
+        meta = entry.get("versions", {}).get(version, {})
+        local = store.read_latest(name)
+        if local == version:
+            state = "installed"
+        elif local:
+            state = f"update ({local})"
+        else:
+            state = "-"
+        rows.append(
+            {
+                "model": name,
+                "version": version,
+                "description": entry.get("description", ""),
+                "bytes": meta.get("bytes", 0),
+                "state": state,
+            }
+        )
+    if args.json:
+        print(jsonlib.dumps(rows, indent=2))
+        return 0
+    name_w = max([len("NAME")] + [len(r["model"]) for r in rows])
+    desc_w = 44
+    print(f"{'NAME':<{name_w}}  {'DESCRIPTION':<{desc_w}}  {'SIZE':>8}  {'UPDATED':<11} STATE")
+    for r in rows:
+        print(
+            f"{r['model']:<{name_w}}  {_clip(r['description'], desc_w):<{desc_w}}"
+            f"  {_human_bytes(r['bytes']):>8}  {r['version']:<11} {r['state']}"
+        )
+    return 0
+
+
+def cmd_models(args: argparse.Namespace) -> int:
+    """Local: what's installed in the store."""
+    rows = []
+    for m in store.local_models():
+        rows.append(
+            {
+                "name": f"{m.model}@{m.version}",
+                "bytes": m.bytes,
+                "pulled": time.strftime("%Y-%m-%d", time.localtime(m.path.stat().st_mtime)),
+                "state": "latest" if store.read_latest(m.model) == m.version else "old",
+            }
+        )
+    if not rows:
+        print("nothing installed — try: enano pull personal-goals  (enano list shows what exists)")
+        return 0
+    if args.json:
+        print(jsonlib.dumps(rows, indent=2))
+        return 0
+    name_w = max(len(r["name"]) for r in rows)
+    print(f"{'NAME':<{name_w}}  {'SIZE':>8}  PULLED      STATE")
+    for r in rows:
+        print(f"{r['name']:<{name_w}}  {_human_bytes(r['bytes']):>8}  {r['pulled']}  {r['state']}")
+    return 0
+
+
+def _update_run(args: argparse.Namespace, fetch: bool) -> int:
+    registry = reg.fetch_registry(refresh=True)
+    targets = [args.model] if args.model else sorted({m.model for m in store.local_models()})
+    rows = []
+    for model in targets:
+        entry = reg.registry_models(registry).get(model)
+        if not entry:
+            rows.append({"model": model, "status": "not-in-registry"})
+            if not args.json:
+                print(f"{model}: not in registry")
+            continue
+        latest = entry.get("latest")
+        local_latest = store.read_latest(model)
+        if latest == local_latest:
+            rows.append({"model": model, "current": local_latest, "latest": latest, "status": "up-to-date"})
+            if not args.json:
+                print(f"{model}: up to date ({latest})")
+            continue
+        rows.append({"model": model, "current": local_latest, "latest": latest, "status": "update-available"})
+        if not args.json:
+            print(f"{model}: {local_latest or 'none'} -> {latest}")
+        if fetch:
+            _pull(model, reg.resolve_entry(registry, model, latest), quiet=args.json)
+    if args.json:
+        print(jsonlib.dumps(rows, indent=2))
+    return 0
+
+
+def cmd_update(args: argparse.Namespace) -> int:
+    return _update_run(args, fetch=False)
+
+
+def cmd_upgrade(args: argparse.Namespace) -> int:
+    return _update_run(args, fetch=True)
+
+
+def cmd_use(args: argparse.Namespace) -> int:
+    if args.model:
+        registry = reg.fetch_registry(refresh=True)
+        if args.model not in reg.registry_models(registry):
+            raise SystemExit(f"unknown model {args.model!r} (enano list shows what exists)")
+        store.write_default_model(args.model)
+    current = store.default_model()
+    if args.json:
+        print(jsonlib.dumps({"default_model": current}))
+        return 0
+    note = "" if store.resolve_version(current, None) else f" (not installed — enano pull {current})"
+    print(f"default model: {current}{note}")
+    return 0
+
+
+def cmd_info(args: argparse.Namespace) -> int:
+    model, version = _parse_selector(args.model)
+    path = store.resolve_version(model, version)
+    if not path:
+        raise SystemExit(f"{args.model} is not installed (try: enano pull {model})")
+    m = next((lm for lm in store.local_models() if lm.path == path), None)
+    doc = m.version_doc if m else {}
+    info = {
+        "model": model,
+        "version": doc.get("built_at") or path.name,
+        "latest_local": store.read_latest(model),
+        "path": str(path),
+        "disk_mb": round((m.bytes if m else 0) / 1e6, 1),
+        "counts": doc.get("counts", {}),
+        "runnable": (path / "tools" / "scan.py").is_file(),
+    }
+    if args.json:
+        print(jsonlib.dumps(info, indent=2))
+    else:
+        for key, value in info.items():
+            print(f"{key:>12}: {value}")
+    return 0
+
+
+def cmd_rm(args: argparse.Namespace) -> int:
+    model, version = _parse_selector(args.model)
+    if not version:
+        versions = [lm.version for lm in store.local_models() if lm.model == model]
+        if len(versions) == 1:
+            version = versions[0]
+        elif versions:
+            raise SystemExit(f"multiple versions installed: {versions} — pick {model}@<version>")
+    if store.read_latest(model) == version:
+        prompt = f"{model}@{version} is what 'latest' points at — remove it anyway? [y/N] "
+        if sys.stdin.isatty():
+            if input(prompt).strip().lower() not in ("y", "yes"):
+                raise SystemExit(2)
+        else:
+            raise SystemExit(
+                f"refusing to remove {model}@{version}: 'latest' points at it (confirm on a terminal)"
+            )
+    if store.remove_version(model, version, force=True):
+        if args.json:
+            print(jsonlib.dumps({"removed": f"{model}@{version}"}))
+        else:
+            print(f"removed {model}@{version}")
+        return 0
+    raise SystemExit(f"{model}@{version} is not installed")
+
+
+def cmd_prune(args: argparse.Namespace) -> int:
+    everything = args.target == "all"
+    removed = []
+    for m in store.local_models():
+        if not everything and store.read_latest(m.model) == m.version:
+            continue
+        store.remove_version(m.model, m.version, force=True)
+        removed.append(f"{m.model}@{m.version}")
+    if everything:
+        shutil.rmtree(store.models_root(), ignore_errors=True)
+    if args.json:
+        print(jsonlib.dumps({"removed": removed, "store_emptied": everything}))
+        return 0
+    for name in removed:
+        print(f"removed {name}")
+    if everything and removed:
+        print("store emptied")
+    if not removed:
+        print("nothing to prune")
+    return 0
+
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    if args.model:
+        bundle = _require_bundle(args.model, auto_pull=False)
+        targets = [m for m in store.local_models() if m.path == bundle]
+    else:
+        targets = store.local_models()
+    results = []
+    for m in targets:
+        tool = m.path / "tools" / "verify.py"
+        if not tool.is_file():
+            results.append({"model": m.model, "version": m.version, "ok": None, "note": "no verify tool in bundle"})
+            continue
+        out = subprocess.run(
+            [sys.executable, str(tool)], cwd=str(m.path), capture_output=True, text=True
+        )
+        results.append(
+            {"model": m.model, "version": m.version, "ok": out.returncode == 0, "output": out.stdout.strip()}
+        )
+    ok = all(r.get("ok") for r in results)
+    if args.json:
+        print(jsonlib.dumps({"ok": ok, "results": results}, indent=2))
+    else:
+        for r in results:
+            mark = "ok" if r.get("ok") else ("n/a" if r.get("ok") is None else "FAIL")
+            print(f"[{mark}] {r['model']}@{r['version']}")
+            if r.get("output") and not r.get("ok"):
+                print("    " + r["output"].replace("\n", "\n    "))
+    return 0 if ok else 1
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    bundle = _require_bundle(store.default_model(), auto_pull=True, quiet=args.json)
+    forward = list(args.forward)
+    json_flag = ["--json"] if args.json else []
+    if forward:
+        return _run_tool(bundle, "scan", forward + json_flag)
+    if not sys.stdin.isatty():
+        return _run_tool(bundle, "scan", ["-"] + json_flag)
+    docs = sorted(Path.cwd().glob("*.md"))
+    if not docs:
+        raise SystemExit("no .md files in the current directory (or pass a file: enano scan notes.md)")
+    print(f"scanning {len(docs)} markdown file(s) in {Path.cwd()}", flush=True)
+    failed = 0
+    for doc in docs:
+        print(f"\n===== {doc.name} =====", flush=True)
+        failed += _run_tool(bundle, "scan", [str(doc)] + json_flag) != 0
+    return 1 if failed else 0
+
+
+SKIP_DIRS = {"node_modules", "__pycache__", ".venv"}
+
+
+def _walk_docs(root: Path) -> list[Path]:
+    docs = []
+    for path in sorted(root.rglob("*.md")):
+        dirs = path.relative_to(root).parts[:-1]
+        if any(part in SKIP_DIRS or part.startswith(".") for part in dirs):
+            continue
+        docs.append(path)
+    return docs
+
+
+def cmd_walk(args: argparse.Namespace) -> int:
+    bundle = _require_bundle(store.default_model(), auto_pull=True, quiet=args.json)
+    tool = bundle / "tools" / "scan.py"
+    if not tool.is_file():
+        raise SystemExit(f"this bundle ships no scanner ({bundle.name})")
+    root = Path(args.directory) if args.directory else Path.cwd()
+    if not root.is_dir():
+        raise SystemExit(f"not a directory: {root}")
+    docs = _walk_docs(root)
+    if not docs:
+        raise SystemExit(f"no .md files under {root}")
+    if args.json:
+        results = []
+        failed = 0
+        for doc in docs:
+            out = subprocess.run(
+                [sys.executable, str(tool), str(doc), "--json"],
+                cwd=str(bundle), capture_output=True, text=True,
+            )
+            ok = out.returncode == 0
+            failed += 0 if ok else 1
+            try:
+                parsed = jsonlib.loads(out.stdout)
+            except jsonlib.JSONDecodeError:
+                parsed = out.stdout.strip()
+            results.append({"path": str(doc.relative_to(root)), "ok": ok, "result": parsed})
+        print(jsonlib.dumps(
+            {"root": str(root), "files": len(results), "failed": failed, "results": results}, indent=2
+        ))
+        return 1 if failed else 0
+    print(f"walking {len(docs)} markdown file(s) under {root}", flush=True)
+    failed = 0
+    for doc in docs:
+        print(f"\n===== {doc.relative_to(root)} =====", flush=True)
+        failed += _run_tool(bundle, "scan", [str(doc)]) != 0
+    return 1 if failed else 0
+
+
+def cmd_elevators(args: argparse.Namespace) -> int:
+    bundle = _require_bundle(store.default_model(), auto_pull=False)
+    forward = list(args.forward)
+    if args.json:
+        forward.append("--json")
+    return _run_tool(bundle, "elevators", forward)
+
+
+def cmd_elevations(args: argparse.Namespace) -> int:
+    bundle = _require_bundle(store.default_model(), auto_pull=False)
+    forward = list(args.forward)
+    if args.query and not any(a in forward for a in ("--search", "--id", "--elevator")):
+        forward = ["--search", args.query, *forward]
+    if args.json:
+        forward.append("--json")
+    return _run_tool(bundle, "elevations", forward)
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    checks = []
+
+    def line(label: str, detail: str, good: bool) -> None:
+        checks.append({"check": label, "detail": detail, "ok": good})
+
+    import importlib.util
+
+    line("python", sys.version.split()[0], sys.version_info >= (3, 9))
+    root = store.store_root()
+    try:
+        root.mkdir(parents=True, exist_ok=True)
+        probe = root / ".write-test"
+        probe.write_text("x")
+        probe.unlink()
+        line("store", str(root), True)
+    except OSError as exc:
+        line("store", f"{root}: {exc}", False)
+    line("disk free", f"{shutil.disk_usage(root).free / 1e9:.1f} GB", shutil.disk_usage(root).free > 500e6)
+    try:
+        registry = reg.fetch_registry(refresh=True)
+        line("registry", f"{len(reg.registry_models(registry))} model(s) indexed", True)
+    except SystemExit as exc:
+        line("registry", str(exc), False)
+    line("default model", store.default_model(), True)
+    line("onnxruntime", "installed (semantic on)" if importlib.util.find_spec("onnxruntime") else "absent (regex-only fallback)", True)
+    for m in store.local_models():
+        doc = m.version_doc
+        line(
+            f"{m.model}@{m.version}",
+            f"verified manifest, runnable={m.runnable}" if doc else "VERSION.json unreadable",
+            bool(doc),
+        )
+    ok = all(c["ok"] for c in checks)
+    if args.json:
+        print(jsonlib.dumps({"ok": ok, "checks": checks}, indent=2))
+    else:
+        for c in checks:
+            print(f"  [{'ok' if c['ok'] else 'FAIL'}] {c['check']:<20} {c['detail']}")
+        print("doctor:", "healthy" if ok else "problems found")
+    return 0 if ok else 1
+
+
+# ------------------------------------------------------------------- parser
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="enano",
+        description="Elevation models on your machine: pull versioned bundles, scan documents deterministically.",
+    )
+    parser.add_argument("--version", action="version", version=f"enano {__version__}")
+    parser.add_argument("--no-color", action="store_true", help=argparse.SUPPRESS)
+    sub = parser.add_subparsers(dest="command")
+
+    p = sub.add_parser("pull", help="download and install a model bundle")
+    p.add_argument("selectors", nargs="*", help="model[@version] … or 'all' (default version: latest)")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_pull)
+
+    p = sub.add_parser("list", help="list registry models (what you can pull)")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_list)
+
+    p = sub.add_parser("models", help="list installed models")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_models)
+
+    p = sub.add_parser("update", help="check for newer versions of local models")
+    p.add_argument("model", nargs="?", help="limit to one model")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_update)
+
+    p = sub.add_parser("upgrade", help="fetch newer versions and re-point latest")
+    p.add_argument("model", nargs="?", help="limit to one model")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_upgrade)
+
+    p = sub.add_parser("use", help="show or set the default model")
+    p.add_argument("model", nargs="?", help="model name (omit to just show)")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_use)
+
+    p = sub.add_parser("info", help="manifest + counts + path for an installed model")
+    p.add_argument("model", help="model[@version]")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_info)
+
+    p = sub.add_parser("rm", help="remove an installed version")
+    p.add_argument("model", help="model[@version]")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_rm)
+
+    p = sub.add_parser("prune", help="remove non-latest local versions ('all': empty the store)")
+    p.add_argument("target", nargs="?", help="'all' to remove everything")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_prune)
+
+    p = sub.add_parser("verify", help="verify bundle checksums against VERSION.json")
+    p.add_argument("model", nargs="?", help="model[@version]; omit to verify everything local")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_verify)
+
+    p = sub.add_parser("scan", help="scan a document with the default model (enano use switches it); no file: every .md in the current folder")
+    p.add_argument("--json", action="store_true")
+    p.add_argument("forward", nargs=argparse.REMAINDER, help=argparse.SUPPRESS)
+    p.set_defaults(func=cmd_scan)
+
+    p = sub.add_parser("walk", help="scan every .md under a folder, recursively")
+    p.add_argument("directory", nargs="?", help="folder to walk (default: the current one)")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_walk)
+
+    p = sub.add_parser("elevators", help="list the default model's source works (enano use switches it)")
+    p.add_argument("--json", action="store_true")
+    p.add_argument("forward", nargs=argparse.REMAINDER, help=argparse.SUPPRESS)
+    p.set_defaults(func=cmd_elevators)
+
+    p = sub.add_parser("elevations", help="search the default model's rule corpus (enano use switches it)")
+    p.add_argument("query", nargs="?", help="search text (positional)")
+    p.add_argument("--json", action="store_true")
+    p.add_argument("forward", nargs=argparse.REMAINDER, help=argparse.SUPPRESS)
+    p.set_defaults(func=cmd_elevations)
+
+    p = sub.add_parser("doctor", help="environment + store diagnostics")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_doctor)
+
+    p = sub.add_parser("help", help="show help (for one command: enano help scan)")
+    p.add_argument("topic", nargs="?", help="command name (default: top-level help)")
+    p.set_defaults(func=cmd_help)
+
+    return parser
+
+
+def cmd_help(args: argparse.Namespace) -> int:
+    parser = build_parser()
+    if not args.topic:
+        parser.print_help()
+        return 0
+    subaction = next((a for a in parser._actions if isinstance(a, argparse._SubParsersAction)), None)
+    target = subaction.choices.get(args.topic) if subaction else None
+    if target is None:
+        raise SystemExit(f"unknown command {args.topic!r} — try: enano help")
+    target.print_help()
+    return 0
+
+
+def cmd_bare() -> int:
+    """Bare `enano`: onboard with the default model — pull it if missing,
+    then show the shortest path to a first scan."""
+    model = store.default_model()
+    path = store.resolve_version(model, None)
+    if not path:
+        print(f"no models installed — pulling the default ({model}) …")
+        entry = reg.resolve_entry(reg.fetch_registry(refresh=True), model, None)
+        _pull(model, entry)
+        path = store.resolve_version(model, None)
+    if path:
+        print(f"ready: {model} is installed ({path.name})")
+    print()
+    print("  enano scan notes.md      scan one document")
+    print("  enano scan                scan every .md in the current folder")
+    print("  enano walk                scan every .md in every subfolder")
+    print("  enano list                see every model you can pull")
+    print(f"  enano use <model>         switch the default (now: {model})")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        return cmd_bare()
+    forward = getattr(args, "forward", None)
+    if forward and forward[:1] == ["--"]:
+        args.forward = forward[1:]
+    return args.func(args) or 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

enano-0.2.0/enano/registry.py

@@ -0,0 +1,112 @@
+"""Registry client: fetch the index, verify and download bundle artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import tempfile
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+DEFAULT_REGISTRY_URL = (
+    "https://amplify-ddcl74bt0u5nd-mai-enanopacksbucket30a8cb47-dzorvtabphoz"
+    ".s3.us-east-2.amazonaws.com/builtin-data/model-zips/registry.json"
+)
+
+
+def registry_url() -> str:
+    import os
+
+    return os.environ.get("ETINY_REGISTRY", DEFAULT_REGISTRY_URL)
+
+
+def fetch_registry(refresh: bool = False, cache_path: Path | None = None) -> dict[str, Any]:
+    """Fetch the registry index; cache it in the store between commands."""
+    from .store import registry_cache_path
+
+    path = cache_path or registry_cache_path()
+    if not refresh and path.is_file():
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            pass
+    doc = _get_json(registry_url())
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(doc, indent=2), encoding="utf-8")
+    return doc
+
+
+def _get_json(url: str) -> Any:
+    with urllib.request.urlopen(url, timeout=30) as response:
+        if response.status != 200:
+            raise SystemExit(f"registry fetch failed: {url} -> {response.status}")
+        return json.loads(response.read().decode("utf-8"))
+
+
+def registry_models(registry: dict[str, Any]) -> dict[str, Any]:
+    return registry.get("models", {})
+
+
+def resolve_entry(registry: dict[str, Any], model: str, version: str | None) -> dict[str, Any]:
+    models = registry_models(registry)
+    if model not in models:
+        known = ", ".join(sorted(models)) or "none published"
+        raise SystemExit(f"unknown model {model!r} (registry has: {known})")
+    entry = models[model]
+    if version is None:
+        version = entry.get("latest")
+        if not version:
+            raise SystemExit(f"model {model!r} has no 'latest' version in the registry")
+    versions = entry.get("versions", {})
+    if version not in versions:
+        raise SystemExit(
+            f"unknown version {model}@{version} (available: {', '.join(sorted(versions))})"
+        )
+    return {"model": model, "version": version, **versions[version]}
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def download_archive(url: str, expected_bytes: int, sha256: str, dest_dir: Path) -> Path:
+    """Stream a bundle zip to disk, verifying size + sha. Progress readout
+    only when attached to a terminal; piped/CI output stays clean."""
+    import sys
+
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / url.rsplit("/", 1)[-1]
+    tty = sys.stdout.isatty()
+    with tempfile.NamedTemporaryFile(dir=dest_dir, delete=False, suffix=".part") as tmp:
+        with urllib.request.urlopen(url, timeout=60) as response:
+            if response.status != 200:
+                raise SystemExit(f"download failed: {url} -> {response.status}")
+            total = int(response.headers.get("Content-Length") or expected_bytes)
+            done = 0
+            if not tty:
+                print(f"  downloading {total / 1e6:.1f} MB …", flush=True)
+            while True:
+                chunk = response.read(1 << 18)
+                if not chunk:
+                    break
+                tmp.write(chunk)
+                done += len(chunk)
+                if tty:
+                    pct = min(100, round(done * 100 / total)) if total else 0
+                    print(f"\r  {pct:>3}%  {done / 1e6:6.1f} / {total / 1e6:.1f} MB", end="", flush=True)
+        if tty:
+            print()
+        if expected_bytes and done != expected_bytes:
+            raise SystemExit(f"size mismatch: got {done} bytes, registry says {expected_bytes}")
+        tmp_path = Path(tmp.name)
+    digest = sha256_file(tmp_path)
+    if digest != sha256:
+        tmp_path.unlink(missing_ok=True)
+        raise SystemExit(f"sha256 mismatch: {digest} != {sha256} — download corrupted or tampered")
+    tmp_path.replace(dest)
+    return dest

enano-0.2.0/enano/store.py

@@ -0,0 +1,164 @@
+"""Local bundle store: ~/.enano layout (legacy ~/.etiny still honored)."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_HOME = Path.home() / ".enano"
+_LEGACY_HOME = Path.home() / ".etiny"
+
+
+def store_root() -> Path:
+    env = os.environ.get("ENANO_HOME") or os.environ.get("ETINY_HOME")
+    if env:
+        return Path(env)
+    if _LEGACY_HOME.is_dir():
+        return _LEGACY_HOME
+    return DEFAULT_HOME
+
+
+def registry_cache_path() -> Path:
+    return store_root() / "registry.json"
+
+
+def default_model() -> str:
+    """The model `use` selected (persisted); falls back to the global default."""
+    pointer = store_root() / "default-model"
+    if pointer.is_file():
+        value = pointer.read_text(encoding="utf-8").strip()
+        if value:
+            return value
+    return "personal-goals"
+
+
+def write_default_model(model: str) -> None:
+    root = store_root()
+    root.mkdir(parents=True, exist_ok=True)
+    (root / "default-model").write_text(model, encoding="utf-8")
+
+
+def models_root() -> Path:
+    return store_root() / "models"
+
+
+def model_dir(model: str, version: str) -> Path:
+    return models_root() / model / version
+
+
+@dataclass
+class LocalModel:
+    model: str
+    version: str
+    path: Path
+    bytes: int
+
+    @property
+    def version_doc(self) -> dict:
+        path = self.path / "VERSION.json"
+        if not path.is_file():
+            return {}
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return {}
+
+    @property
+    def runnable(self) -> bool:
+        return (self.path / "tools" / "scan.py").is_file()
+
+
+def read_latest(model: str) -> str | None:
+    pointer = models_root() / model / "latest"
+    if pointer.is_symlink():
+        target = pointer.resolve()
+        return target.name if target.is_dir() else None
+    if pointer.is_file():
+        value = pointer.read_text(encoding="utf-8").strip()
+        return value or None
+    return None
+
+
+def write_latest(model: str, version: str) -> None:
+    pointer = models_root() / model / "latest"
+    if pointer.is_symlink() or pointer.is_file():
+        pointer.unlink()
+    try:
+        pointer.symlink_to(version, target_is_directory=True)
+    except OSError:
+        pointer.write_text(version, encoding="utf-8")
+
+
+def resolve_version(model: str, version: str | None) -> Path | None:
+    """Resolve name or name@version to a bundle directory on disk."""
+    if version:
+        path = model_dir(model, version)
+        return path if path.is_dir() else None
+    latest = read_latest(model)
+    if not latest:
+        return None
+    path = model_dir(model, latest)
+    return path if path.is_dir() else None
+
+
+def local_models() -> list[LocalModel]:
+    out: list[LocalModel] = []
+    root = models_root()
+    if not root.is_dir():
+        return out
+    for model_path in sorted(root.iterdir()):
+        if not model_path.is_dir():
+            continue
+        for version_path in sorted(model_path.iterdir()):
+            if not version_path.is_dir() or version_path.name == "latest":
+                continue
+            out.append(
+                LocalModel(
+                    model=model_path.name,
+                    version=version_path.name,
+                    path=version_path,
+                    bytes=sum(f.stat().st_size for f in version_path.rglob("*") if f.is_file()),
+                )
+            )
+    return out
+
+
+def install_bundle(model: str, version: str, archive: Path) -> Path:
+    """Extract a bundle zip into the store and point latest at it.
+
+    The zip contains a single top-level directory (enano-<model>-model-<date>
+    or etiny-...); its contents are lifted into models/<model>/<version>/ so
+    the store is addressed by clean names regardless of the artifact naming.
+    """
+    staging = model_dir(model, f".{version}.tmp")
+    if staging.exists():
+        shutil.rmtree(staging)
+    staging.mkdir(parents=True)
+    with zipfile.ZipFile(archive) as bundle:
+        bundle.extractall(staging)
+    top = [p for p in staging.iterdir() if p.is_dir()]
+    payload = top[0] if len(top) == 1 else staging
+    target = model_dir(model, version)
+    if target.exists():
+        shutil.rmtree(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(payload), str(target))
+    shutil.rmtree(staging, ignore_errors=True)
+    write_latest(model, version)
+    return target
+
+
+def remove_version(model: str, version: str, force: bool = False) -> bool:
+    path = model_dir(model, version)
+    if not path.is_dir():
+        return False
+    if read_latest(model) == version and not force:
+        raise SystemExit(
+            f"refusing to remove {model}@{version}: 'latest' points at it (use --force)"
+        )
+    shutil.rmtree(path)
+    return True

enano-0.2.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "enano"
+version = "0.2.0"
+description = "Elevation models for personal goals and pitch decks: pull versioned bundles, scan documents deterministically, entirely on your machine."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+keywords = ["goals", "habits", "pitch-decks", "deterministic", "cli"]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+]
+
+[project.optional-dependencies]
+semantic = ["onnxruntime"]
+
+[project.scripts]
+enano = "enano.cli:main"
+# Legacy alias so existing muscle memory keeps working.
+etiny = "enano.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["enano"]