jdsl 0.6.2__py3-none-any.whl

jdsl/__init__.py

@@ -0,0 +1,116 @@
+"""jdsl — behavior-tree agents with DSPy-style signatures, run by a tree-walking
+interpreter. Authoring surface: tool, root, seq, sel, repeat, act, check, predict, ref, store."""
+
+from jdsl.context import Blackboard, ContextWindow, ModelTurn, Ref, RunContext, ToolCall, Write
+from jdsl.dsl import (
+    act,
+    check,
+    guard,
+    guard_call,
+    invert,
+    oneshot,
+    optional,
+    predict,
+    react,
+    ref,
+    repeat,
+    root,
+    sel,
+    seq,
+    store,
+    timeout,
+    tool,
+)
+from jdsl.provider import LanguageModel
+from jdsl.render import render
+from jdsl.trace import (
+    BlobStore,
+    EventKind,
+    EventSource,
+    JsonlTraceSink,
+    ListTraceSink,
+    NullTraceSink,
+    Redactor,
+    SafeSink,
+    TraceEvent,
+    read_events,
+    segment_episodes,
+)
+from jdsl.tree import (
+    Action,
+    Check,
+    Decorator,
+    Guard,
+    GuardCall,
+    Invert,
+    Node,
+    OneShot,
+    Optional,
+    Predict,
+    React,
+    Repeat,
+    Root,
+    Selector,
+    Sequence,
+    Status,
+    Timeout,
+    assign_runtime_ids,
+)
+
+__all__ = [
+    "tool",
+    "act",
+    "seq",
+    "sel",
+    "repeat",
+    "check",
+    "guard",
+    "guard_call",
+    "predict",
+    "react",
+    "invert",
+    "optional",
+    "timeout",
+    "oneshot",
+    "root",
+    "store",
+    "ref",
+    "render",
+    "Ref",
+    "Status",
+    "Node",
+    "Action",
+    "Check",
+    "Guard",
+    "GuardCall",
+    "Repeat",
+    "Sequence",
+    "Selector",
+    "Predict",
+    "React",
+    "Decorator",
+    "Invert",
+    "Optional",
+    "Timeout",
+    "OneShot",
+    "Root",
+    "LanguageModel",
+    "RunContext",
+    "Blackboard",
+    "ContextWindow",
+    "ToolCall",
+    "ModelTurn",
+    "Write",
+    "assign_runtime_ids",
+    "TraceEvent",
+    "EventKind",
+    "EventSource",
+    "NullTraceSink",
+    "ListTraceSink",
+    "JsonlTraceSink",
+    "SafeSink",
+    "BlobStore",
+    "Redactor",
+    "read_events",
+    "segment_episodes",
+]

jdsl/cli.py

@@ -0,0 +1,387 @@
+"""The jdsl CLI: runtime (`config`, `run`, `show`) plus the harness/compiler
+control surface (`capture`, `compile`, `package`, `harness`) from design §37.
+
+Harness commands import `jdsl_harness` lazily, so the dependency-light runtime core
+keeps working when the harness extra is not installed."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+import typer
+
+from jdsl import config
+from jdsl.render import render
+from jdsl.tree import Root
+
+app = typer.Typer(
+    add_completion=False,
+    help=("Declarative behavior-tree agents. Read docs at "
+          "https://cantor-industries.github.io/jdsl-py/ to understand what jdsl is."),
+)
+config_app = typer.Typer(help="Manage provider API keys (~/.local/share/recon/auth.json).")
+app.add_typer(config_app, name="config")
+
+package_app = typer.Typer(help="Inspect, verify, and run compiled .jdsl behavior packages.")
+capture_app = typer.Typer(help="List and inspect captured trace sets.")
+harness_app = typer.Typer(help="Run the local harness daemon (ingest + control plane).")
+app.add_typer(package_app, name="package")
+app.add_typer(capture_app, name="capture")
+app.add_typer(harness_app, name="harness")
+
+
+def _store_root() -> Path:
+    """Where the harness keeps its store; overridable via JDSL_HARNESS_HOME."""
+    return Path(os.environ.get("JDSL_HARNESS_HOME") or (Path.home() / ".local/share/jdsl-harness"))
+
+
+@config_app.command("add")
+def config_add(
+    keys: list[str] = typer.Argument(..., help="One or more API keys to store."),
+    provider: str = typer.Option("anthropic", "-p", "--provider", help="Provider name."),
+) -> None:
+    """Store API keys for a provider (de-duplicated, merged)."""
+    try:
+        merged = config.add_keys(provider, keys)
+    except ValueError as err:
+        typer.secho(str(err), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from None
+    typer.secho(
+        f"Stored {len(keys)} key(s) for {provider!r} ({len(merged)} total) at {config.auth_path()}.",
+        fg=typer.colors.GREEN,
+    )
+
+
+@config_app.command("list")
+def config_list() -> None:
+    """Print the current auth config with keys masked."""
+    current = config.load()
+    if not current:
+        typer.echo("No stored credentials.")
+        return
+    for provider, entry in current.items():
+        typer.secho(provider, fg=typer.colors.CYAN, bold=True)
+        for key in entry.get("api_keys", []):
+            typer.echo(f"  {_mask(key)}")
+
+
+@app.command("run")
+def run(
+    file: Path = typer.Argument(..., exists=True, readable=True, help="A .py file defining skills."),
+    inputs: list[str] = typer.Option(
+        [], "-i", "--input", help="Seed a blackboard input as key=value (repeatable)."
+    ),
+) -> None:
+    """Import ``file`` and execute every ``root()`` skill defined at module level."""
+    seed = dict(_parse_kv(item) for item in inputs)
+    module = _load_module(file)
+    roots = [v for v in vars(module).values() if isinstance(v, Root)]
+    if not roots:
+        typer.secho(f"No skills (root(...)) found in {file}.", fg=typer.colors.YELLOW)
+        raise typer.Exit(1)
+    for skill in roots:
+        typer.secho(f"▶ running {skill.name!r}", fg=typer.colors.CYAN, bold=True)
+        ctx = skill.run(**seed)
+        if ctx.blackboard:
+            typer.echo(f"  blackboard: {dict(ctx.blackboard)}")
+        for w in ctx.blackboard.clobbers():
+            typer.secho(f"  ⚠ {w.key!r} overwritten by {w.writer} (was set by another node)",
+                        fg=typer.colors.YELLOW)
+
+
+@app.command("show")
+def show(file: Path = typer.Argument(..., exists=True, readable=True, help="A .py file defining skills.")) -> None:
+    """Print each skill's structure as an ASCII tree (no execution, no model)."""
+    module = _load_module(file)
+    roots = [v for v in vars(module).values() if isinstance(v, Root)]
+    if not roots:
+        typer.secho(f"No skills (root(...)) found in {file}.", fg=typer.colors.YELLOW)
+        raise typer.Exit(1)
+    for skill in roots:
+        typer.echo(render(skill))
+
+
+def _parse_kv(item: str) -> tuple[str, str]:
+    if "=" not in item: raise typer.BadParameter(f"--input must be key=value, got {item!r}.")
+    key, value = item.split("=", 1)
+    return key.strip(), value
+
+
+def _load_module(file: Path):
+    spec = importlib.util.spec_from_file_location(file.stem, file)
+    if spec is None or spec.loader is None: raise typer.BadParameter(f"Cannot import {file}.")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def _mask(key: str) -> str:
+    return "*" * len(key) if len(key) <= 8 else f"{key[:4]}…{key[-4:]}"
+
+
+# -- package commands (§37) ---------------------------------------------------
+
+@package_app.command("inspect")
+def package_inspect(path: Path = typer.Argument(..., exists=True, help="A .jdsl or package dir.")) -> None:
+    """Show a package's manifest, capabilities, and burden metrics."""
+    from jdsl.package import load_package
+    pkg = load_package(path)
+    m = pkg.manifest
+    typer.secho(f"{m.name} v{m.version}  [{m.format}]", fg=typer.colors.CYAN, bold=True)
+    typer.echo(f"  task family: {m.task_family or 'n/a'}")
+    typer.echo(f"  verification: {m.verification.get('status', 'unverified')} "
+               f"(replay coverage {m.verification.get('replay_coverage', 'n/a')})")
+    typer.echo(f"  fidelity: {m.source.get('capture_fidelity', 'n/a')}, "
+               f"episodes: {m.source.get('episode_count', 'n/a')}")
+    perms = pkg.permissions()
+    typer.secho("  reads:  " + (", ".join(perms["reads"]) or "(none)"), fg=typer.colors.GREEN)
+    typer.secho("  writes: " + (", ".join(perms["writes"]) or "(none)"),
+                fg=typer.colors.RED if perms["writes"] else typer.colors.GREEN)
+
+
+@package_app.command("verify")
+def package_verify(path: Path = typer.Argument(..., exists=True, help="A .jdsl or package dir.")) -> None:
+    """Structurally verify a package and its digests; exit non-zero on failure."""
+    from jdsl.package import PackageError, load_package
+    try:
+        load_package(path)  # load_package runs digest + structural verification
+    except PackageError as err:
+        typer.secho(f"✗ invalid package: {err}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from None
+    typer.secho("✓ package is structurally valid and digests match.", fg=typer.colors.GREEN)
+
+
+@package_app.command("run")
+def package_run(
+    path: Path = typer.Argument(..., exists=True, help="A .jdsl or package dir."),
+    tools: Path = typer.Option(..., "-t", "--tools", exists=True,
+                               help="A .py file exposing TOOLS (dict) and optional PREDICATES."),
+    model: str = typer.Option(None, "-m", "--model", help="Model id for residual leaves."),
+    inputs: list[str] = typer.Option([], "-i", "--input", help="Seed blackboard key=value."),
+) -> None:
+    """Bind a package to host tools and run it with a (small) model."""
+    from jdsl.package import load_package
+    pkg = load_package(path)
+    mod = _load_module(tools)
+    tool_map = getattr(mod, "TOOLS", None)
+    if not isinstance(tool_map, dict):
+        typer.secho(f"{tools} must define a TOOLS dict (logical_id -> callable).", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    predicates = getattr(mod, "PREDICATES", {})
+    seed = dict(_parse_kv(item) for item in inputs)
+    root = pkg.as_root(tool_map, predicates, model_id=model)
+    ctx = root.run(**seed)
+    typer.echo(f"  blackboard: {dict(ctx.blackboard)}")
+
+
+# -- capture commands (§37) ---------------------------------------------------
+
+@capture_app.command("start")
+def capture_start(
+    host: str = typer.Option("host", help="Source host name."),
+    adapter: str = typer.Option("hook", help="Capture adapter name."),
+    note: str = typer.Option("", help="Optional capture note."),
+) -> None:
+    """Start a token-protected capture and print hook credentials."""
+    from jdsl_harness.capture import CaptureCoordinator
+    from jdsl_harness.store import HarnessStore
+    session = CaptureCoordinator(HarnessStore(_store_root())).start_session(
+        host=host, adapter=adapter, note=note)
+    typer.echo(f"capture_id={session.capture_id}")
+    typer.echo(f"capture_token={session.token}")
+    typer.echo("Export both values to the host hook environment.")
+
+@capture_app.command("list")
+def capture_list() -> None:
+    """List captures in the local harness store."""
+    from jdsl_harness.store import HarnessStore
+    for c in HarnessStore(_store_root()).list_captures():
+        typer.echo(f"{c['capture_id']}  {c['status']:9} episodes={c['episodes']}  {c.get('note','')}")
+
+
+@capture_app.command("import")
+def capture_import(
+    file: Path = typer.Argument(..., exists=True, readable=True,
+                                help="JSONL file: one episode per line {episode_id, steps:[...], outcome}."),
+    capture_id: str = typer.Option(..., "-c", "--capture", help="Capture id to import into."),
+) -> None:
+    """Import foreign agent logs into a capture (Tier C, §8.3)."""
+    from jdsl_harness.adapters.import_jsonl import import_records_file
+    from jdsl_harness.store import HarnessStore
+    store = HarnessStore(_store_root())
+    events = import_records_file(file, capture_id=capture_id)
+    for event in events:
+        store.ingest(event)
+    typer.secho(f"imported {len(events)} events into {capture_id}.", fg=typer.colors.GREEN)
+
+
+@capture_app.command("inspect")
+def capture_inspect(capture_id: str = typer.Argument(..., help="Capture id.")) -> None:
+    """Print the exact-lineage report for a capture (§51)."""
+    from jdsl_harness.capture import CaptureCoordinator
+    from jdsl_harness.store import HarnessStore
+    coord = CaptureCoordinator(HarnessStore(_store_root()))
+    typer.echo(json.dumps(coord.lineage_report(capture_id), indent=2, default=str))
+
+
+@app.command("compile")
+def compile_cmd(
+    capture_id: str = typer.Argument(..., help="Capture id to compile."),
+    name: str = typer.Option("behavior", "-n", "--name", help="Package name."),
+    out: Path = typer.Option(None, "-o", "--out", help="Write a .jdsl to this path."),
+) -> None:
+    """Compile a capture into a verified behavior package (§24)."""
+    from jdsl.package import export_jdsl, package_digest
+    from jdsl_harness.compiler import compile_behavior
+    from jdsl_harness.store import HarnessStore
+    store = HarnessStore(_store_root())
+    result = compile_behavior(store.capture_episodes(capture_id), name=name)
+    typer.echo(json.dumps(result.report(), indent=2, default=str))
+    if out is not None:
+        path = export_jdsl(result.package, out)
+        store.record_package(name, result.package.manifest.version, package_digest(result.package),
+                             status="built", path=str(path))
+        typer.secho(f"→ wrote {path}", fg=typer.colors.GREEN)
+
+
+# -- harness daemon (§37) -----------------------------------------------------
+
+@harness_app.command("serve")
+def harness_serve(
+    host: str = typer.Option("127.0.0.1", help="Bind host (loopback by default)."),
+    port: int = typer.Option(8848, help="Ingest port."),
+) -> None:
+    """Run the local ingest server (data plane). Ctrl-C to stop."""
+    from jdsl_harness.server import IngestServer
+    from jdsl_harness.store import HarnessStore
+    server = IngestServer(HarnessStore(_store_root()), host=host, port=port).start()
+    typer.secho(f"jdsl harness ingest listening on {server.url} (store: {_store_root()})",
+                fg=typer.colors.CYAN)
+    try:
+        import time
+        while True:
+            time.sleep(3600)
+    except KeyboardInterrupt:
+        server.stop()
+        typer.echo("stopped.")
+
+
+@app.command("tui")
+def tui() -> None:
+    """Open the local skill-authoring workbench."""
+    try:
+        from jdsl.tui import run
+    except ModuleNotFoundError as error:
+        if error.name == "textual":
+            raise typer.BadParameter("install the TUI with `pip install jdsl[tui]`") from error
+        raise
+    run()
+
+
+def _print_install_banner():
+    green = "\033[0;32m"
+    muted = "\033[0;2m"
+    nc = "\033[0m"
+    typer.echo(f"{green}        _        _            _            _     {nc}")
+    typer.echo(f"{green}       /\\ \\     /\\ \\         / /\\         _\\ \\   {nc}")
+    typer.echo(f"{green}       \\ \\ \\   /  \\ \\____   / /  \\       /\\__ \\  {nc}")
+    typer.echo(f"{green}        /\\ \\_\\ / /\\ \\_____\\ / / /\\ \\__   / /_ \\_\\ {nc}")
+    typer.echo(f"{green}       / /\\_// / /\\/___  // / /\\ \\___\\ / / /\\/_/ {nc}")
+    typer.echo(f"{green}  _   / / /  / / /   / / / \\ \\ \\ \\/___// / /      {nc}")
+    typer.echo(f"{green} /\\ \\ / / /  / / /   / / /   \\ \\ \\     / / /       {nc}")
+    typer.echo(f"{green} \\ \\_\\/ / /  / / /   / / /_    \\ \\ \\   / / / ____   {nc}")
+    typer.echo(f"{green}  / / /_/ / /  \\ \\__/ / //_\\__/ / /  / /_/_/ ___/\\ {nc}")
+    typer.echo(f"{green} / / /__\\/ /    \\ \\___\\/ / \\ \\/___/ /  /_______/\\__/ {nc}")
+    typer.echo(f"{green}\\/_______/      \\/_____/   \\_____\\/   \\_______\\/  {nc}")
+    typer.echo(f"{muted}Quick start:{nc}")
+    typer.echo("  jdsl run examples/greeter.py")
+    typer.echo("")
+    typer.echo(f"{muted}For API keys:{nc}")
+    typer.echo("  echo 'ANTHROPIC_API_KEY=sk-...' >> .env")
+    typer.echo("")
+    typer.echo(f"{muted}Docs: {nc}https://cantor-industries.github.io/jdsl-py/")
+    typer.echo("")
+
+
+@app.callback()
+def main():
+    """Declarative behavior-tree agents.
+
+    Read docs at https://cantor-industries.github.io/jdsl-py/.
+    """
+    # After any subcommand runs, show the banner once on first run or via --about
+    pass
+
+
+@app.command("about")
+def about():
+    """Show jdsl info and quickstart."""
+    typer.secho("jdsl — Declarative behavior-tree agents", fg=typer.colors.CYAN, bold=True)
+    _print_install_banner()
+
+
+@app.command("uninstall")
+def uninstall(
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Remove the curl-installed CLI while preserving captures and credentials."""
+    install_root = Path.home() / ".jdsl"
+    if not install_root.exists():
+        typer.echo("No curl-installed jdsl CLI found.")
+        return
+    if not yes and not typer.confirm(f"Remove {install_root} and its PATH entry?", default=False):
+        typer.echo("Cancelled.")
+        return
+
+    shutil.rmtree(install_root)
+    removed = _remove_install_path_entries()
+    typer.secho("Removed the curl-installed jdsl CLI.", fg=typer.colors.GREEN)
+    if removed:
+        typer.echo("Removed its PATH entry from: " + ", ".join(removed))
+    typer.echo("Harness captures and provider credentials were preserved.")
+
+
+def _remove_install_path_entries() -> list[str]:
+    install_dir = Path.home() / ".jdsl" / "bin"
+    config_home = Path(os.environ.get("XDG_CONFIG_HOME") or (Path.home() / ".config"))
+    shell = Path(os.environ.get("SHELL", "sh")).name
+    if shell == "fish":
+        files = [Path.home() / ".config/fish/config.fish"]
+    elif shell == "zsh":
+        zdotdir = Path(os.environ.get("ZDOTDIR") or Path.home())
+        files = [zdotdir / ".zshrc", zdotdir / ".zshenv", config_home / "zsh/.zshrc", config_home / "zsh/.zshenv"]
+    elif shell == "bash":
+        files = [Path.home() / ".bashrc", Path.home() / ".bash_profile", Path.home() / ".profile",
+                 config_home / "bash/.bashrc", config_home / "bash/.bash_profile"]
+    else:
+        files = [Path.home() / ".bashrc", Path.home() / ".bash_profile", config_home / "bash/.bashrc",
+                 config_home / "bash/.bash_profile"]
+
+    removed: list[str] = []
+    path_line = f"export PATH={install_dir}:$PATH"
+    fish_line = f"fish_add_path {install_dir}"
+    for path in dict.fromkeys(files):
+        if not path.is_file():
+            continue
+        lines = path.read_text(encoding="utf-8").splitlines()
+        filtered: list[str] = []
+        for line in lines:
+            if line.strip() in (path_line, fish_line):
+                if filtered and filtered[-1].strip() == "# jdsl":
+                    filtered.pop()
+                continue
+            filtered.append(line)
+        if filtered != lines:
+            path.write_text("\n".join(filtered).rstrip() + "\n", encoding="utf-8")
+            removed.append(str(path))
+    return removed
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

jdsl/config.py

@@ -0,0 +1,80 @@
+"""Credential storage + provider inference. Keys live in
+~/.local/share/recon/auth.json as {"<provider>": {"api_keys": [...]}}, and a
+.env in the working directory is loaded on import."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()  # so DEEPSEEK_API_KEY etc. are picked up without exporting
+
+SUPPORTED_PROVIDERS = ("anthropic", "openai", "deepseek", "google", "tinker")
+
+ENV_KEYS = {
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "deepseek": "DEEPSEEK_API_KEY",
+    "google": "GOOGLE_API_KEY",
+    "tinker": "TINKER_API_KEY",
+}
+
+# OpenAI-compatible base URLs (Anthropic uses its own SDK, so it's absent).
+BASE_URLS = {
+    "deepseek": "https://api.deepseek.com",
+    "openai": None,
+    "tinker": "https://tinker.thinkingmachines.dev/services/tinker-prod/oai/api/v1",
+}
+
+
+def provider_for_model(model_id: str) -> str:
+    name = model_id.lower()
+    if name.startswith("claude"): return "anthropic"
+    if name.startswith("deepseek"): return "deepseek"
+    if name.startswith(("gpt", "o1", "o3", "o4")): return "openai"
+    if name.startswith("gemini"): return "google"
+    if name.startswith(("thinkingmachines/", "inkling")): return "tinker"
+    return "anthropic"
+
+
+def config_dir() -> Path:
+    base = os.environ.get("XDG_DATA_HOME") or (Path.home() / ".local" / "share")
+    return Path(base) / "recon"
+
+
+def auth_path() -> Path: return config_dir() / "auth.json"
+
+
+def load() -> dict[str, dict[str, list[str]]]:
+    path = auth_path()
+    return json.loads(path.read_text()) if path.exists() else {}
+
+
+def save(config: dict[str, dict[str, list[str]]]) -> None:
+    path = auth_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(config, indent=2))
+
+
+def add_keys(provider: str, keys: list[str]) -> list[str]:
+    """Merge keys into provider's list, de-duplicating. Returns the merged list."""
+    if provider not in SUPPORTED_PROVIDERS:
+        raise ValueError(f"Unknown provider {provider!r}. Supported: {', '.join(SUPPORTED_PROVIDERS)}.")
+    config = load()
+    merged = list(config.get(provider, {}).get("api_keys", []))
+    for key in keys:
+        if key not in merged: merged.append(key)
+    config[provider] = {"api_keys": merged}
+    save(config)
+    return merged
+
+
+def keys_for(provider: str) -> list[str]:
+    """Stored keys for provider, else the provider's env var."""
+    stored = load().get(provider, {}).get("api_keys", [])
+    if stored: return list(stored)
+    env_value = os.environ.get(ENV_KEYS.get(provider, ""))
+    return [env_value] if env_value else []