nexus-lite 0.2.2__py3-none-any.whl

nexus_lite/__init__.py

@@ -0,0 +1,190 @@
+"""
+nexus-lite: Open-Core Kernel for Nexus multi-agent primitives.
+
+Eagerly loads only the light modules (`pty`, `roles`, `protocol`); `core` and the memory tiers
+(`nexus_lite.memory.{stm,mtm,ltm}`) load on first attribute access (PEP 562), so
+`import nexus_lite.memory.ltm` pulls in no other tier.
+
+Demos/orchestration scenarios (`nexus_lite.demos`) and Colab helpers (`nexus_lite.colab`) are
+outside the kernel; their old top-level names resolve lazily with a DeprecationWarning.
+"""
+
+from __future__ import annotations
+
+import importlib
+import warnings
+from importlib import metadata as _metadata
+from typing import Any
+
+from . import protocol
+from . import pty
+from . import roles
+from .protocol import (
+    POINTER_MAX_CHARS,
+    format_pointer_line,
+    parse_pointer_line,
+    pointer_parts,
+    sanitize_pointer_token,
+    truncate_words,
+)
+from .pty import (
+    KEY_MAP,
+    KEY_NAMES,
+    key_to_bytes,
+    keys_to_bytes,
+)
+from .roles import (
+    REAL_AGENTS,
+    ROLE_FOR_AGENT,
+    ROLE_PROMPTS,
+    ROLE_TIER,
+    TIER_ORDER,
+    get_role_prompt,
+    resolve_role_dispatch,
+    tier_for_role,
+    tier_rank,
+)
+
+try:  # single source of truth: pyproject.toml via installed metadata
+    __version__ = _metadata.version("nexus-lite")
+except _metadata.PackageNotFoundError:  # bare source tree / shipped bundle: read pyproject.toml if adjacent
+    import re as _re
+    from pathlib import Path as _Path
+
+    try:
+        _m = _re.search(r'(?m)^version\s*=\s*"([^"]+)"',
+                        (_Path(__file__).resolve().parent.parent / "pyproject.toml").read_text(encoding="utf-8"))
+    except OSError:
+        _m = None
+    __version__ = _m.group(1) if _m else "0+unknown"
+
+_LAZY_MODULES = {"compute", "core", "demos"}
+
+_LAZY_SYMBOLS: dict[str, str] = {
+    # compute (zero-preinstall remote execution on Turing & Colab)
+    "compute_run": "compute",
+    "pack_lite_bundle": "compute",
+    "pack_self_contained_script": "compute",
+    "run_local_sandbox": "compute",
+    "run_on_colab": "compute",
+    "run_on_turing": "compute",
+    "turing_job_status": "compute",
+    # core
+    "chat": "core",
+    "delegate": "core",
+    "ensure_opencode": "core",
+    "run_pipeline": "core",
+    "run_swarm": "core",
+    # _db / memory tiers
+    "get_workspace": "_db",
+    "init": "_db",
+    "bus_read": "memory.mtm",
+    "bus_send": "memory.mtm",
+    "wiki_list": "memory.ltm",
+    "wiki_read": "memory.ltm",
+    "wiki_search": "memory.ltm",
+    "wiki_write": "memory.ltm",
+    "stm_list": "memory.stm",
+    "stm_pack": "memory.stm",
+    "stm_read": "memory.stm",
+    "stm_rebuild_index": "memory.stm",
+    "stm_search": "memory.stm",
+    "stm_write": "memory.stm",
+}
+
+# Deprecated top-level names: resolved lazily with a DeprecationWarning.
+_DEPRECATED_SYMBOLS: dict[str, str] = {
+    "get_db": "_db",
+    "get_db_path": "_db",
+    **{n: "demos.scenarios" for n in (
+        "run_all_demos", "run_hipaa_privacy_pipeline", "run_lung1_audit_pipeline",
+        "run_multimodal_imaging_swarm", "run_opencode_free_demo", "run_phantom_shape_swarm")},
+    **{n: "demos.orchestration" for n in (
+        "run_agent_interaction", "run_cooperative_problem_solver", "run_multi_tier_swarm")},
+    **{n: "demos.viz" for n in ("dashboard", "render_dashboard_html", "watch")},
+    **{n: "colab.env" for n in (
+        "ColabInitResult", "detect_env", "ensure_colab", "ensure_env", "sync_dotdir_to_drive")},
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY_MODULES:
+        mod = importlib.import_module(f".{name}", __name__)
+        globals()[name] = mod
+        return mod
+    if name in _LAZY_SYMBOLS:
+        mod_name = _LAZY_SYMBOLS[name]
+        mod = importlib.import_module(f".{mod_name}", __name__)
+        val = getattr(mod, name)
+        globals()[name] = val
+        return val
+    if name in _DEPRECATED_SYMBOLS:
+        mod_name = _DEPRECATED_SYMBOLS[name]
+        warnings.warn(
+            f"nexus_lite.{name} is deprecated; use nexus_lite.{mod_name}.{name}",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return getattr(importlib.import_module(f".{mod_name}", __name__), name)
+    if name == "stm":  # deprecated module alias, see nexus_lite/stm.py
+        warnings.warn(
+            "nexus_lite.stm is deprecated; import nexus_lite.memory.stm instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return importlib.import_module(".memory.stm", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "pty",
+    "compute",
+    "core",
+    "roles",
+    "protocol",
+    "compute_run",
+    "run_on_turing",
+    "run_on_colab",
+    "run_local_sandbox",
+    "pack_lite_bundle",
+    "pack_self_contained_script",
+    "turing_job_status",
+    "init",
+    "get_workspace",
+    "bus_send",
+    "bus_read",
+    "delegate",
+    "run_swarm",
+    "run_pipeline",
+    "stm_write",
+    "stm_read",
+    "stm_list",
+    "stm_search",
+    "stm_pack",
+    "stm_rebuild_index",
+    "wiki_write",
+    "wiki_read",
+    "wiki_search",
+    "wiki_list",
+    "chat",
+    "ensure_opencode",
+    "POINTER_MAX_CHARS",
+    "sanitize_pointer_token",
+    "truncate_words",
+    "format_pointer_line",
+    "pointer_parts",
+    "parse_pointer_line",
+    "KEY_NAMES",
+    "KEY_MAP",
+    "key_to_bytes",
+    "keys_to_bytes",
+    "ROLE_PROMPTS",
+    "ROLE_FOR_AGENT",
+    "REAL_AGENTS",
+    "ROLE_TIER",
+    "TIER_ORDER",
+    "tier_rank",
+    "tier_for_role",
+    "resolve_role_dispatch",
+    "get_role_prompt",
+]

nexus_lite/__main__.py

@@ -0,0 +1,7 @@
+"""Allow `python -m nexus_lite` (same entrypoint as the `nexus-lite` console script)."""
+import sys
+
+from nexus_lite.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

nexus_lite/_db.py

@@ -0,0 +1,196 @@
+"""
+nexus_lite._db — workspace path + SQLite WAL connection + schema bootstrap.
+
+Shared by the memory tiers (stm/mtm/ltm) and the task/session code in core. Stdlib
+only; imports no other nexus_lite module at import time.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Iterator, Optional, Union
+
+
+def get_workspace() -> Path:
+    """Return canonical workspace root Path (.nexus/ or NEXUS_LITE_DIR or NEXUS_LITE_HOME)."""
+    env = os.environ.get("NEXUS_LITE_DIR") or os.environ.get("NEXUS_LITE_HOME")
+    if env:
+        return Path(env).resolve()
+    return Path(".nexus").resolve()
+
+
+def get_db_path() -> Path:
+    """Return path to SQLite WAL database."""
+    return get_workspace() / "lite.db"
+
+
+def mark_session(name: str, live: bool) -> None:
+    """Best-effort: flip an EXISTING sessions-registry row live/unregistered (lite#8).
+
+    Update-only and never creates the workspace/DB: a socket with no row already counts as
+    live on the bus, so only a stale 'unregistered' row (or a kill) needs a write. Called by
+    pty.spawn / pty.kill (edge pty -> _db; _db imports no lite module, so no cycle).
+    """
+    try:
+        if not get_db_path().exists():
+            return
+        with connect() as con:
+            if live:
+                con.execute(
+                    "UPDATE sessions SET status = 'live', last_seen = strftime('%s','now') "
+                    "WHERE name = ?;", (name,))
+            else:
+                con.execute("UPDATE sessions SET status = 'unregistered' WHERE name = ?;", (name,))
+    except Exception:
+        pass
+
+
+def get_db() -> sqlite3.Connection:
+    """Open SQLite connection configured with WAL journal mode and Row factory.
+
+    The caller owns the connection and MUST close it (``with con:`` only commits). Prefer
+    :func:`connect`, which commits/rolls back and closes.
+    """
+    db_p = get_db_path()
+    db_p.parent.mkdir(parents=True, exist_ok=True)
+    con = sqlite3.connect(str(db_p), timeout=30.0)
+    con.row_factory = sqlite3.Row
+    con.execute("PRAGMA journal_mode=WAL;")
+    con.execute("PRAGMA synchronous=NORMAL;")
+    return con
+
+
+@contextlib.contextmanager
+def connect() -> Iterator[sqlite3.Connection]:
+    """Yield a connection; commit on success, roll back on error, always close."""
+    con = get_db()
+    try:
+        with con:
+            yield con
+    finally:
+        con.close()
+
+
+# --- schema versioning (PRAGMA user_version) -------------------------------------------
+# v0 = any DB without user_version (the original CREATE TABLE IF NOT EXISTS schema).
+# Table/column names are frozen. Append new steps; never edit old ones.
+
+
+def _m1_stamp_baseline(con: sqlite3.Connection) -> None:
+    """v0 -> v1: baseline schema (created idempotently by _ensure_base_schema); stamp only."""
+
+
+def _m2_bus_v1(con: sqlite3.Connection) -> None:
+    """v1 -> v2 (lite#8): messages.seq (backfilled), bus_cursors, bus_meta, sessions.last_seen."""
+    cols = {r[1] for r in con.execute("PRAGMA table_info(messages);")}
+    if "seq" not in cols:
+        con.execute("ALTER TABLE messages ADD COLUMN seq INTEGER;")
+    rows = con.execute("SELECT rowid FROM messages ORDER BY timestamp, rowid;").fetchall()
+    for i, r in enumerate(rows, 1):
+        con.execute("UPDATE messages SET seq = ? WHERE rowid = ?;", (i, r[0]))
+    con.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_messages_seq ON messages(seq);")
+    con.execute(
+        "CREATE TABLE IF NOT EXISTS bus_cursors ("
+        "target TEXT PRIMARY KEY, acked_seq INTEGER NOT NULL DEFAULT 0, updated REAL);"
+    )
+    con.execute("CREATE TABLE IF NOT EXISTS bus_meta (key TEXT PRIMARY KEY, value INTEGER NOT NULL);")
+    con.execute("INSERT OR REPLACE INTO bus_meta (key, value) VALUES ('last_seq', ?);", (len(rows),))
+    scols = {r[1] for r in con.execute("PRAGMA table_info(sessions);")}
+    if "last_seen" not in scols:
+        con.execute("ALTER TABLE sessions ADD COLUMN last_seen REAL;")
+
+
+MIGRATIONS = [_m1_stamp_baseline, _m2_bus_v1]  # index i migrates v<i> -> v<i+1>
+SCHEMA_VERSION = len(MIGRATIONS)
+
+_BASE_DDL = (
+    """CREATE TABLE IF NOT EXISTS sessions (
+        name TEXT PRIMARY KEY, sock TEXT, cmd TEXT, created_at REAL, status TEXT);""",
+    """CREATE TABLE IF NOT EXISTS messages (
+        id TEXT PRIMARY KEY, sender TEXT, target TEXT, kind TEXT, summary TEXT,
+        path TEXT, content TEXT, timestamp REAL);""",
+    """CREATE TABLE IF NOT EXISTS tasks (
+        id TEXT PRIMARY KEY, caller TEXT, agent_cmd TEXT, status TEXT, rc INTEGER,
+        created_at REAL, completed_at REAL, artifact_dir TEXT);""",
+    "CREATE VIRTUAL TABLE IF NOT EXISTS wiki_fts USING fts5(slug, content);",
+)
+
+
+def migrate(con: sqlite3.Connection) -> int:
+    """Bring `con` to SCHEMA_VERSION inside one transaction; refuse a newer DB."""
+    cur = con.execute("PRAGMA user_version;").fetchone()[0]
+    if cur > SCHEMA_VERSION:
+        raise RuntimeError(
+            f"lite.db schema version {cur} is newer than this nexus_lite supports "
+            f"({SCHEMA_VERSION}); upgrade nexus_lite"
+        )
+    if cur == SCHEMA_VERSION:
+        return cur
+    con.execute("BEGIN IMMEDIATE;")
+    try:
+        cur = con.execute("PRAGMA user_version;").fetchone()[0]  # re-read under the write lock
+        if cur > SCHEMA_VERSION:
+            raise RuntimeError(f"lite.db schema version {cur} is newer than {SCHEMA_VERSION}")
+        for ddl in _BASE_DDL:
+            con.execute(ddl)
+        for i in range(cur, SCHEMA_VERSION):
+            MIGRATIONS[i](con)
+        con.execute(f"PRAGMA user_version = {SCHEMA_VERSION};")
+        con.execute("COMMIT;")
+    except BaseException:
+        con.execute("ROLLBACK;")
+        raise
+    return SCHEMA_VERSION
+
+
+_INIT_DONE: set[str] = set()
+_INIT_LOCK = threading.Lock()
+
+
+def reset_init() -> None:
+    """Forget memoized init() state (tests / explicit re-init)."""
+    with _INIT_LOCK:
+        _INIT_DONE.clear()
+
+
+def init(
+    workspace: Optional[Union[str, Path]] = None,
+    root: Optional[Union[str, Path]] = None,
+    force: bool = False,
+) -> Path:
+    """Initialize workspace layout and SQLite schema; once per (process, db path).
+
+    `force=True` (or :func:`reset_init`) re-runs it.
+    """
+    target = workspace or root
+    if target:
+        ws = Path(target).resolve()
+        os.environ["NEXUS_LITE_HOME"] = str(ws)
+        os.environ["NEXUS_LITE_DIR"] = str(ws)
+    else:
+        ws = get_workspace()
+
+    key = str(get_db_path())
+    if not force and key in _INIT_DONE and Path(key).exists() and (ws / "inbox").is_dir():
+        return ws
+
+    ws.mkdir(parents=True, exist_ok=True)
+    (ws / "inbox").mkdir(parents=True, exist_ok=True)
+    (ws / "artifacts").mkdir(parents=True, exist_ok=True)
+    (ws / "wiki").mkdir(parents=True, exist_ok=True)
+    try:
+        from .memory import stm as _stm  # lazy: keeps _db import-free of the tiers
+
+        _stm.ensure_project_node(ws)
+    except Exception:
+        pass
+
+    with contextlib.closing(get_db()) as con:
+        migrate(con)
+    with _INIT_LOCK:
+        _INIT_DONE.add(key)
+    return ws

nexus_lite/_proc.py

@@ -0,0 +1,17 @@
+"""nexus_lite._proc — reap intentionally detached children. Stdlib only."""
+
+from __future__ import annotations
+
+import subprocess
+import threading
+
+
+def reap_in_background(proc: "subprocess.Popen") -> "subprocess.Popen":
+    """Wait for a detached child on a daemon thread so it never lingers as a zombie.
+
+    The child keeps running independently (start_new_session=True) and outlives this
+    process; the thread only collects its exit status if we are still alive. The thread
+    holds a reference, so no 'subprocess still running' ResourceWarning is emitted.
+    """
+    threading.Thread(target=proc.wait, name=f"reap-{proc.pid}", daemon=True).start()
+    return proc

nexus_lite/artifacts.py

@@ -0,0 +1,83 @@
+"""Task-artifact layout contract (stdlib only, no nexus_lite imports).
+
+One per-task directory holds every artifact of a delegated task:
+
+    <root>/<task_id>/
+        prompt.md   input prompt           output.md  worker stdout (lite name)
+        result.md   same bytes as output.md (code-style readers)
+        meta.json   {task_id, agent, status, rc, started, finished}
+        rc          exit code as text      spec.json  bg runner spec
+        (timeout, runner.pid, runner.log, stderr.log, escalation.json, ...)
+
+Root: ``<workspace>/artifacts``. The root is an argument; a downstream
+multi-project host passes its own root to ``task_dir``/``ensure_task_dir``.
+
+Env exported to workers (one release of overlap):
+    NEXUS_TASK_DIR      canonical per-task directory
+    NEXUS_ARTIFACT_DIR  deprecated alias, same value
+Readers use ``task_dir_from_env``: canonical wins, alias accepted.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Mapping, Optional, Union
+
+PROMPT = "prompt.md"
+OUTPUT = "output.md"
+RESULT = "result.md"
+META = "meta.json"
+RC = "rc"
+SPEC = "spec.json"
+
+TASK_DIR_ENV = "NEXUS_TASK_DIR"
+TASK_DIR_ENV_DEPRECATED = "NEXUS_ARTIFACT_DIR"
+
+PathLike = Union[str, "os.PathLike[str]"]
+
+
+def artifacts_root(workspace: PathLike) -> Path:
+    """Default artifact root: <workspace>/artifacts (no env override)."""
+    return Path(workspace) / "artifacts"
+
+
+def task_dir(task_id: str, root: PathLike) -> Path:
+    """Pure path: <root>/<task_id>."""
+    return Path(root) / task_id
+
+
+def ensure_task_dir(task_id: str, root: PathLike) -> Path:
+    d = task_dir(task_id, root)
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def task_dir_from_env(env: Optional[Mapping[str, str]] = None) -> Optional[Path]:
+    """Per-task dir from env: canonical name wins, deprecated alias accepted."""
+    e = os.environ if env is None else env
+    v = e.get(TASK_DIR_ENV) or e.get(TASK_DIR_ENV_DEPRECATED)
+    return Path(v) if v else None
+
+
+def export_env(env: dict, art_dir: PathLike) -> dict:
+    """Set canonical and deprecated per-task dir vars on ``env`` (in place)."""
+    env[TASK_DIR_ENV] = str(art_dir)
+    env[TASK_DIR_ENV_DEPRECATED] = str(art_dir)
+    return env
+
+
+def write_result(art_dir: PathLike, output: str, rc: int) -> None:
+    """Write output.md, result.md (same content) and rc."""
+    d = Path(art_dir)
+    (d / OUTPUT).write_text(output, encoding="utf-8")
+    (d / RESULT).write_text(output, encoding="utf-8")
+    (d / RC).write_text(str(rc), encoding="utf-8")
+
+
+def write_meta(art_dir: PathLike, *, task_id: str, agent: str, status: str,
+               rc: int, started: float, finished: float) -> None:
+    (Path(art_dir) / META).write_text(
+        json.dumps({"task_id": task_id, "agent": agent, "status": status,
+                    "rc": rc, "started": started, "finished": finished}),
+        encoding="utf-8")