doppler-cli 0.2.6__py3-none-any.whl

doppler_cli/dopplerfile.py

@@ -0,0 +1,195 @@
+"""
+doppler dopplerfile — YAML-defined custom block loader.
+
+A dopplerfile lets you register a pipeline block without writing
+Python.  Drop a small YAML file next to your script and
+``doppler compose init`` picks it up automatically:
+
+    # chirp.yml
+    name: chirp
+    role: source
+    executable: ./chirp.py
+    config:
+        sample_rate: 2048000.0
+        sweep_rate:  50000.0
+        tone_power:  -20.0
+        noise_floor: -90.0
+
+Arg mapping
+-----------
+By default every config field is passed as ``--{field-with-dashes}
+value`` and the socket addresses are injected as:
+
+    source / chain  →  ``--bind  {output_addr}``
+    chain  / sink   →  ``--connect {input_addr}``
+
+For scripts that use different flag names, add an explicit ``args``
+section using ``{placeholder}`` substitution:
+
+    args:
+        output: "{output_addr}"
+        rate:   "{sample_rate}"
+
+Available placeholders are ``{output_addr}``, ``{input_addr}``, and
+any config field name.
+
+Discovery order for ``doppler compose init <name>``:
+    1. Built-in Python registry
+    2. ~/.doppler/blocks/<name>.yml
+    3. ./<name>.yml  (current working directory)
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Type
+
+import yaml
+from pydantic import create_model
+
+from doppler_cli.blocks import Block, BlockConfig
+
+_BLOCKS_DIR = Path.home() / ".doppler" / "blocks"
+
+
+# ---------------------------------------------------------------------------
+# Config synthesis
+# ---------------------------------------------------------------------------
+
+
+def _make_config(defaults: dict[str, Any]) -> Type[BlockConfig]:
+    """Dynamically build a pydantic BlockConfig from a defaults dict."""
+    fields: dict[str, Any] = {}
+    for k, v in defaults.items():
+        fields[k] = (type(v), v)
+    return create_model("DopplerfileConfig", __base__=BlockConfig, **fields)
+
+
+# ---------------------------------------------------------------------------
+# Block synthesis
+# ---------------------------------------------------------------------------
+
+
+def _make_block(
+    name: str,
+    role: str,
+    executable: str,
+    config_defaults: dict[str, Any],
+    args_template: dict[str, str] | None,
+    dependencies: list[str] | None = None,
+) -> Type[Block]:
+    """Return a live Block subclass described by a dopplerfile document."""
+
+    ConfigClass = _make_config(config_defaults)
+
+    def _command(
+        self,
+        config: BlockConfig,
+        input_addr: str | None,
+        output_addr: str | None,
+    ) -> list[str]:
+        exe = self.__class__._exe
+        tmpl = self.__class__._args_template
+        cmd: list[str] = [exe]
+
+        if tmpl is not None:
+            # Explicit template: substitute placeholders
+            ctx: dict[str, Any] = dict(config.model_dump())
+            ctx["output_addr"] = output_addr or ""
+            ctx["input_addr"] = input_addr or ""
+            for flag, value_tmpl in tmpl.items():
+                cmd += [f"--{flag}", value_tmpl.format(**ctx)]
+        else:
+            # Auto-map: inject socket addresses, then all config fields
+            if output_addr is not None:
+                cmd += ["--bind", output_addr]
+            if input_addr is not None:
+                cmd += ["--connect", input_addr]
+            for field, value in config.model_dump().items():
+                flag = "--" + field.replace("_", "-")
+                if isinstance(value, (list, dict)):
+                    cmd += [flag, json.dumps(value)]
+                elif isinstance(value, bool):
+                    if value:
+                        cmd.append(flag)
+                else:
+                    cmd += [flag, str(value)]
+
+        # Wrap with uv run --with <dep> ... for dependency isolation
+        deps = self.__class__._dependencies
+        if deps:
+            with_flags: list[str] = []
+            for dep in deps:
+                with_flags += ["--with", dep]
+            cmd = ["uv", "run"] + with_flags + cmd
+
+        return cmd
+
+    cls = type(
+        f"DopplerfileBlock_{name}",
+        (Block,),
+        {
+            "name": name,
+            "role": role,
+            "Config": ConfigClass,
+            "_exe": executable,
+            "_args_template": args_template,
+            "_dependencies": dependencies or [],
+            "command": _command,
+        },
+    )
+    return cls  # type: ignore[return-value]
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def load(path: Path) -> Type[Block]:
+    """Parse *path* as a dopplerfile and return a Block subclass.
+
+    Parameters
+    ----------
+    path:
+        Path to a YAML dopplerfile.
+
+    Returns
+    -------
+    A Block subclass ready to be used by the compose engine.
+
+    Raises
+    ------
+    KeyError
+        If the dopplerfile is missing a required field.
+    """
+    doc = yaml.safe_load(path.read_text())
+    return _make_block(
+        name=doc["name"],
+        role=doc["role"],
+        executable=doc["executable"],
+        config_defaults=doc.get("config", {}),
+        args_template=doc.get("args"),
+        dependencies=doc.get("dependencies"),
+    )
+
+
+def discover(name: str) -> Type[Block] | None:
+    """Search for a dopplerfile that defines *name*.
+
+    Search order:
+
+    1. ``~/.doppler/blocks/<name>.yml``
+    2. ``./<name>.yml`` (current working directory)
+
+    Returns ``None`` if no dopplerfile is found.
+    """
+    candidates = [
+        _BLOCKS_DIR / f"{name}.yml",
+        Path.cwd() / f"{name}.yml",
+    ]
+    for path in candidates:
+        if path.exists():
+            return load(path)
+    return None

doppler_cli/ports.py

@@ -0,0 +1,44 @@
+"""Auto port allocation for doppler pipeline blocks."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+_BASE_PORT = 5600
+_MAX_PORT = 5700
+_CHAINS_DIR = Path.home() / ".doppler" / "chains"
+
+
+def _in_use() -> set[int]:
+    """Return all ports referenced in active chain state files."""
+    ports: set[int] = set()
+    if not _CHAINS_DIR.exists():
+        return ports
+    for f in _CHAINS_DIR.glob("*.json"):
+        try:
+            state = json.loads(f.read_text())
+        except (json.JSONDecodeError, OSError):
+            continue
+        for block in state.get("blocks", []):
+            for key in ("bind_port", "connect_port"):
+                if (p := block.get(key)) is not None:
+                    ports.add(int(p))
+    return ports
+
+
+def allocate(n: int) -> list[int]:
+    """Return *n* consecutive free ports starting from _BASE_PORT."""
+    used = _in_use()
+    allocated: list[int] = []
+    candidate = _BASE_PORT
+    while len(allocated) < n:
+        if candidate > _MAX_PORT:
+            raise RuntimeError(
+                f"No free ports in range {_BASE_PORT}–{_MAX_PORT}. "
+                "Clean up old chains with `doppler ps` and `doppler stop`."
+            )
+        if candidate not in used and candidate not in allocated:
+            allocated.append(candidate)
+        candidate += 1
+    return allocated

doppler_cli/ps.py

@@ -0,0 +1,116 @@
+"""doppler ps / stop / kill / logs / inspect commands."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+from doppler_cli.state import ChainState, list_chains, pid_alive, stop_chain
+
+console = Console()
+
+
+def cmd_ps() -> None:
+    """List running chains."""
+    chains = list_chains()
+    if not chains:
+        console.print("[dim]No chains running.[/dim]")
+        return
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("ID", style="cyan")
+    table.add_column("Started")
+    table.add_column("Blocks")
+    table.add_column("Status")
+
+    for chain in chains:
+        alive = [b for b in chain.blocks if pid_alive(b.pid)]
+        status = (
+            "[green]running[/green]"
+            if len(alive) == len(chain.blocks)
+            else f"[yellow]{len(alive)}/{len(chain.blocks)} alive[/yellow]"
+        )
+        block_names = ", ".join(b.name for b in chain.blocks)
+        table.add_row(chain.id, chain.started[:19], block_names, status)
+
+    console.print(table)
+
+
+def cmd_stop(chain_id: str) -> None:
+    """Gracefully stop a chain (SIGTERM)."""
+    chain = ChainState.load(chain_id)
+    stop_chain(chain, kill=False)
+    console.print(f"Stopped chain [cyan]{chain_id}[/cyan].")
+
+
+def cmd_kill(chain_id: str) -> None:
+    """Forcefully kill a chain (SIGKILL)."""
+    chain = ChainState.load(chain_id)
+    stop_chain(chain, kill=True)
+    console.print(f"Killed chain [cyan]{chain_id}[/cyan].")
+
+
+def cmd_inspect(chain_id: str) -> None:
+    """Print resolved config and PIDs for a chain."""
+    chain = ChainState.load(chain_id)
+    console.print_json(
+        json.dumps(
+            {
+                "id": chain.id,
+                "started": chain.started,
+                "compose": chain.compose,
+                "blocks": [
+                    {
+                        "name": b.name,
+                        "pid": b.pid,
+                        "alive": pid_alive(b.pid),
+                        "bind_port": b.bind_port,
+                        "connect_port": b.connect_port,
+                    }
+                    for b in chain.blocks
+                ],
+            }
+        )
+    )
+
+
+def cmd_logs(chain_id: str, block_name: str | None = None) -> None:
+    """Stream logs for a chain or a specific block.
+
+    Since each block is an independent subprocess, we tail the journal
+    (systemd) or fall back to printing PIDs for manual inspection.
+    """
+    chain = ChainState.load(chain_id)
+    targets = (
+        [b for b in chain.blocks if b.name == block_name]
+        if block_name
+        else chain.blocks
+    )
+    if not targets:
+        console.print(
+            f"[red]Block {block_name!r} not found in chain {chain_id!r}.[/red]"
+        )
+        sys.exit(1)
+
+    log_files = [b.log_file for b in targets if b.log_file]
+    if not log_files:
+        pids = [str(b.pid) for b in targets]
+        console.print(
+            "[yellow]No log files for this chain.[/yellow] "
+            f"(Chain may have been started before log support was added.) "
+            f"Block PIDs: {', '.join(pids)}"
+        )
+        return
+
+    available = [f for f in log_files if Path(f).exists()]
+    for f in log_files:
+        if f not in available:
+            console.print(f"[yellow]Log file not found:[/yellow] {f}")
+
+    if available:
+        subprocess.run(["tail", "-f", *available], check=False)  # noqa: S603

doppler_cli/source.py

@@ -0,0 +1,125 @@
+"""
+doppler-source — streaming IQ source entry point.
+
+Generates synthetic IQ samples and pushes them over a ZMQ PUSH socket
+so they can be consumed by downstream blocks in a doppler pipeline.
+
+Usage
+-----
+    doppler-source --type tone --bind tcp://127.0.0.1:5600 [options]
+"""
+
+from __future__ import annotations
+
+import argparse
+import signal
+from datetime import datetime, timezone
+
+BLOCK_SIZE = 4096  # samples per push frame
+
+
+def _log(msg: str) -> None:
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    print(f"[{ts}] {msg}", flush=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="doppler-source",
+        description="doppler streaming IQ source",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "--type",
+        required=True,
+        choices=["tone"],
+        help="Source type",
+    )
+    parser.add_argument(
+        "--bind",
+        required=True,
+        metavar="ADDR",
+        help="ZMQ PUSH bind address, e.g. tcp://127.0.0.1:5600",
+    )
+    parser.add_argument(
+        "--fs",
+        type=float,
+        default=2.048e6,
+        metavar="Hz",
+        help="Sample rate",
+    )
+    parser.add_argument(
+        "--center",
+        type=float,
+        default=0.0,
+        metavar="Hz",
+        help="Center frequency (metadata only)",
+    )
+    parser.add_argument(
+        "--tone-freq",
+        type=float,
+        default=100e3,
+        metavar="Hz",
+        help="Tone offset from DC",
+    )
+    parser.add_argument(
+        "--tone-power",
+        type=float,
+        default=-20.0,
+        metavar="DBM",
+        help="Tone power in dBm",
+    )
+    parser.add_argument(
+        "--noise-floor",
+        type=float,
+        default=-90.0,
+        metavar="DBM",
+        help="AWGN noise floor in dBm",
+    )
+
+    args = parser.parse_args()
+
+    from doppler.stream import CF64, Push  # noqa: PLC0415
+    from doppler_specan.source import DemoSource  # noqa: PLC0415
+
+    _log(
+        f"doppler-source started — type=tone bind={args.bind}"
+        f" fs={args.fs:.0f} tone_freq={args.tone_freq:.0f}Hz"
+        f" tone_power={args.tone_power}dBm noise_floor={args.noise_floor}dBm"
+    )
+
+    source = DemoSource(
+        sample_rate=args.fs,
+        center_freq=args.center,
+        tone_freq=args.tone_freq,
+        tone_power=args.tone_power,
+        noise_floor=args.noise_floor,
+    )
+
+    # Graceful shutdown on SIGTERM
+    _running = True
+
+    def _stop(signum, frame):
+        nonlocal _running
+        _running = False
+
+    signal.signal(signal.SIGTERM, _stop)
+
+    try:
+        with Push(args.bind, CF64) as push:
+            while _running:
+                iq, fs, cf = source.read(BLOCK_SIZE)
+                push.send(
+                    iq.astype("complex128"),
+                    sample_rate=fs,
+                    center_freq=cf,
+                )
+    except KeyboardInterrupt:
+        pass
+    finally:
+        source.close()
+        _log("doppler-source stopped")
+
+
+if __name__ == "__main__":
+    main()

doppler_cli/state.py

@@ -0,0 +1,109 @@
+"""Chain state persistence in ~/.doppler/chains/."""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_CHAINS_DIR = Path.home() / ".doppler" / "chains"
+
+
+@dataclass
+class BlockState:
+    name: str
+    pid: int
+    bind_port: int | None = None  # output port this block binds
+    connect_port: int | None = None  # input port this block connects to
+    log_file: str | None = None  # stderr/stdout log path
+
+
+@dataclass
+class ChainState:
+    id: str
+    started: str
+    compose: str
+    blocks: list[BlockState] = field(default_factory=list)
+
+    def save(self) -> None:
+        _CHAINS_DIR.mkdir(parents=True, exist_ok=True)
+        path = _CHAINS_DIR / f"{self.id}.json"
+        path.write_text(json.dumps(self._to_dict(), indent=2))
+
+    def delete(self) -> None:
+        path = _CHAINS_DIR / f"{self.id}.json"
+        path.unlink(missing_ok=True)
+
+    def _to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "started": self.started,
+            "compose": self.compose,
+            "blocks": [
+                {
+                    "name": b.name,
+                    "pid": b.pid,
+                    "bind_port": b.bind_port,
+                    "connect_port": b.connect_port,
+                    "log_file": b.log_file,
+                }
+                for b in self.blocks
+            ],
+        }
+
+    @classmethod
+    def load(cls, chain_id: str) -> "ChainState":
+        path = _CHAINS_DIR / f"{chain_id}.json"
+        if not path.exists():
+            raise KeyError(f"No chain with id {chain_id!r}")
+        data = json.loads(path.read_text())
+        blocks = [
+            BlockState(
+                name=b["name"],
+                pid=b["pid"],
+                bind_port=b.get("bind_port"),
+                connect_port=b.get("connect_port"),
+                log_file=b.get("log_file"),
+            )
+            for b in data.get("blocks", [])
+        ]
+        return cls(
+            id=data["id"],
+            started=data["started"],
+            compose=data["compose"],
+            blocks=blocks,
+        )
+
+
+def list_chains() -> list[ChainState]:
+    if not _CHAINS_DIR.exists():
+        return []
+    chains = []
+    for f in sorted(_CHAINS_DIR.glob("*.json")):
+        try:
+            chains.append(ChainState.load(f.stem))
+        except (KeyError, json.JSONDecodeError, OSError):
+            continue
+    return chains
+
+
+def pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except (ProcessLookupError, PermissionError):
+        return False
+
+
+def stop_chain(chain: ChainState, kill: bool = False) -> None:
+    """Send SIGTERM (or SIGKILL) to all block processes."""
+    sig = signal.SIGKILL if kill else signal.SIGTERM
+    for block in chain.blocks:
+        if pid_alive(block.pid):
+            try:
+                os.kill(block.pid, sig)
+            except ProcessLookupError:
+                pass
+    chain.delete()