doppler-cli 0.2.6__py3-none-any.whl

doppler_cli/__init__.py

@@ -0,0 +1,3 @@
+"""doppler-cli — signal processing pipeline orchestration."""
+
+__version__ = "0.1.0"

doppler_cli/__main__.py

@@ -0,0 +1,180 @@
+"""
+doppler — signal processing pipeline CLI.
+
+Usage
+-----
+    doppler ps
+    doppler stop <ID>
+    doppler kill <ID>
+    doppler inspect <ID>
+    doppler logs <ID> [--block NAME]
+
+    doppler compose init <BLOCK...>
+    doppler compose up <FILE>
+    doppler compose down <ID>
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Import blocks to populate the registry
+import doppler_cli.blocks.fir  # noqa: F401
+import doppler_cli.blocks.specan  # noqa: F401
+import doppler_cli.blocks.tone  # noqa: F401
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="doppler",
+        description="doppler signal processing pipeline CLI",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    # --- ps ---
+    sub.add_parser("ps", help="List running chains")
+
+    # --- stop ---
+    p_stop = sub.add_parser("stop", help="Gracefully stop a chain")
+    p_stop.add_argument("id", metavar="ID")
+
+    # --- kill ---
+    p_kill = sub.add_parser("kill", help="Forcefully kill a chain")
+    p_kill.add_argument("id", metavar="ID")
+
+    # --- inspect ---
+    p_inspect = sub.add_parser("inspect", help="Show resolved config and PIDs")
+    p_inspect.add_argument("id", metavar="ID")
+
+    # --- logs ---
+    p_logs = sub.add_parser("logs", help="Stream logs from a chain")
+    p_logs.add_argument("id", metavar="ID")
+    p_logs.add_argument(
+        "--block",
+        default=None,
+        metavar="NAME",
+        help="Show logs for a specific block only",
+    )
+
+    # --- compose ---
+    p_compose = sub.add_parser("compose", help="Manage compose chains")
+    compose_sub = p_compose.add_subparsers(dest="compose_cmd", metavar="SUBCOMMAND")
+
+    p_init = compose_sub.add_parser(
+        "init",
+        help="Scaffold a compose file with default config",
+    )
+    p_init.add_argument(
+        "blocks",
+        nargs="+",
+        metavar="BLOCK",
+        help="Ordered block names, e.g. tone fir specan",
+    )
+    p_init.add_argument(
+        "--name",
+        default=None,
+        metavar="NAME",
+        help=(
+            "Human-readable chain name (default: random hex ID). "
+            "Used as the filename stem and chain ID."
+        ),
+    )
+    p_init.add_argument(
+        "--out",
+        default=None,
+        metavar="FILE",
+        help="Write compose file to FILE (default: ~/.doppler/chains/<ID>.yml)",
+    )
+
+    p_up = compose_sub.add_parser("up", help="Start a chain from a compose file")
+    p_up.add_argument(
+        "file",
+        metavar="FILE",
+        nargs="?",
+        default=None,
+        help="Compose file to start (default: most recently created)",
+    )
+
+    p_down = compose_sub.add_parser("down", help="Stop a running chain")
+    p_down.add_argument("id", metavar="ID")
+
+    args = parser.parse_args()
+
+    # Dispatch
+    if args.command == "ps":
+        from doppler_cli.ps import cmd_ps  # noqa: PLC0415
+
+        cmd_ps()
+
+    elif args.command == "stop":
+        from doppler_cli.ps import cmd_stop  # noqa: PLC0415
+
+        cmd_stop(args.id)
+
+    elif args.command == "kill":
+        from doppler_cli.ps import cmd_kill  # noqa: PLC0415
+
+        cmd_kill(args.id)
+
+    elif args.command == "inspect":
+        from doppler_cli.ps import cmd_inspect  # noqa: PLC0415
+
+        cmd_inspect(args.id)
+
+    elif args.command == "logs":
+        from doppler_cli.ps import cmd_logs  # noqa: PLC0415
+
+        cmd_logs(args.id, args.block)
+
+    elif args.command == "compose":
+        if args.compose_cmd == "init":
+            from doppler_cli.compose import init  # noqa: PLC0415
+
+            out = Path(args.out) if args.out else None
+            path = init(args.blocks, out=out, name=args.name)
+            print(f"wrote {path}")
+
+        elif args.compose_cmd == "up":
+            from doppler_cli.compose import up  # noqa: PLC0415
+            from doppler_cli.state import _CHAINS_DIR  # noqa: PLC0415
+
+            if args.file:
+                p = Path(args.file)
+                # Bare name (no path separators) → resolve to chains dir
+                if not p.parts[1:] and not p.suffix:
+                    p = _CHAINS_DIR / f"{args.file}.yml"
+                compose_file = p
+            else:
+                ymls = sorted(
+                    _CHAINS_DIR.glob("*.yml"),
+                    key=lambda p: p.stat().st_mtime,
+                    reverse=True,
+                )
+                if not ymls:
+                    print("no compose files found in ~/.doppler/chains/")
+                    sys.exit(1)
+                compose_file = ymls[0]
+                print(f"using {compose_file}")
+            state = up(compose_file)
+            print(f"started chain {state.id} ({len(state.blocks)} blocks)")
+
+        elif args.compose_cmd == "down":
+            from doppler_cli.compose import down  # noqa: PLC0415
+
+            down(args.id)
+            print(f"stopped chain {args.id}")
+
+        else:
+            p_compose.print_help()
+            sys.exit(1)
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

doppler_cli/blocks/__init__.py

@@ -0,0 +1,76 @@
+"""Block base class and registry."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import ClassVar, Type
+
+from pydantic import BaseModel
+
+
+class BlockConfig(BaseModel):
+    """Base config for all blocks."""
+
+    pass
+
+
+class Block(ABC):
+    """Base class for all doppler pipeline blocks.
+
+    Subclasses declare a ``name`` and a ``Config`` pydantic model.
+    The CLI uses the Config schema to scaffold compose file defaults
+    and to validate user-supplied overrides.
+
+    A block has zero or one input port and zero or one output port:
+
+    - source: no input, one output (binds PUSH)
+    - chain:  one input (connects PULL), one output (binds PUSH)
+    - sink:   one input (connects PULL), no output
+    """
+
+    name: ClassVar[str]
+    Config: ClassVar[Type[BlockConfig]]
+
+    #: "source" | "chain" | "sink"
+    role: ClassVar[str]
+
+    @abstractmethod
+    def command(
+        self,
+        config: BlockConfig,
+        input_addr: str | None,
+        output_addr: str | None,
+    ) -> list[str]:
+        """Return the argv list to spawn this block as a subprocess."""
+        ...
+
+
+# Registry: name → Block subclass
+_REGISTRY: dict[str, Type[Block]] = {}
+
+
+def register(cls: Type[Block]) -> Type[Block]:
+    """Decorator to register a Block subclass by name."""
+    _REGISTRY[cls.name] = cls
+    return cls
+
+
+def get(name: str) -> Type[Block]:
+    if name in _REGISTRY:
+        return _REGISTRY[name]
+    # Fall back to dopplerfile discovery
+    from doppler_cli import dopplerfile  # noqa: PLC0415
+
+    cls = dopplerfile.discover(name)
+    if cls is not None:
+        return cls
+    available = ", ".join(sorted(_REGISTRY))
+    raise KeyError(
+        f"Unknown block {name!r}. Built-ins: {available}\n"
+        f"  Or add a dopplerfile: ~/.doppler/blocks/{name}.yml "
+        f"or ./{name}.yml"
+    )
+
+
+def all_blocks() -> dict[str, Type[Block]]:
+    return dict(_REGISTRY)

doppler_cli/blocks/fir.py

@@ -0,0 +1,35 @@
+"""FIR filter chain block."""
+
+from __future__ import annotations
+
+from doppler_cli.blocks import Block, BlockConfig, register
+
+
+class FirConfig(BlockConfig):
+    taps: list[float] = []
+
+
+@register
+class FirBlock(Block):
+    name = "fir"
+    Config = FirConfig
+    role = "chain"
+
+    def command(
+        self,
+        config: FirConfig,
+        input_addr: str | None,
+        output_addr: str | None,
+    ) -> list[str]:
+        assert input_addr is not None
+        assert output_addr is not None
+        cmd = [
+            "doppler-fir",
+            "--connect",
+            input_addr,
+            "--bind",
+            output_addr,
+        ]
+        if config.taps:
+            cmd += ["--taps", *[str(t) for t in config.taps]]
+        return cmd

doppler_cli/blocks/specan.py

@@ -0,0 +1,56 @@
+"""Specan sink block — spectrum analyzer display."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from doppler_cli.blocks import Block, BlockConfig, register
+
+
+class SpecanConfig(BlockConfig):
+    mode: Literal["terminal", "web"] = "web"
+    center: float = 0.0
+    span: float | None = None
+    rbw: float | None = None
+    level: float | None = None
+    web_port: int = 8080
+    web_host: str = "127.0.0.1"
+
+
+@register
+class SpecanBlock(Block):
+    name = "specan"
+    Config = SpecanConfig
+    role = "sink"
+
+    def command(
+        self,
+        config: SpecanConfig,
+        input_addr: str | None,
+        output_addr: str | None,
+    ) -> list[str]:
+        assert input_addr is not None
+        cmd = [
+            "doppler-specan",
+            "--source",
+            "pull",
+            "--address",
+            input_addr,
+        ]
+        if config.center:
+            cmd += ["--center", str(config.center)]
+        if config.span is not None:
+            cmd += ["--span", str(config.span)]
+        if config.rbw is not None:
+            cmd += ["--rbw", str(config.rbw)]
+        if config.level is not None:
+            cmd += ["--level", str(config.level)]
+        if config.mode == "web":
+            cmd += [
+                "--web",
+                "--port",
+                str(config.web_port),
+                "--host",
+                config.web_host,
+            ]
+        return cmd

doppler_cli/blocks/tone.py

@@ -0,0 +1,45 @@
+"""Tone source block — synthetic complex tone + AWGN."""
+
+from __future__ import annotations
+
+from doppler_cli.blocks import Block, BlockConfig, register
+
+
+class ToneConfig(BlockConfig):
+    sample_rate: float = 2.048e6
+    center_freq: float = 0.0
+    tone_freq: float = 100e3
+    tone_power: float = -20.0
+    noise_floor: float = -90.0
+
+
+@register
+class ToneBlock(Block):
+    name = "tone"
+    Config = ToneConfig
+    role = "source"
+
+    def command(
+        self,
+        config: ToneConfig,
+        input_addr: str | None,
+        output_addr: str | None,
+    ) -> list[str]:
+        assert output_addr is not None
+        return [
+            "doppler-source",
+            "--type",
+            "tone",
+            "--bind",
+            output_addr,
+            "--fs",
+            str(config.sample_rate),
+            "--center",
+            str(config.center_freq),
+            "--tone-freq",
+            str(config.tone_freq),
+            "--tone-power",
+            str(config.tone_power),
+            "--noise-floor",
+            str(config.noise_floor),
+        ]

doppler_cli/compose.py

@@ -0,0 +1,207 @@
+"""doppler compose — init, up, down."""
+
+from __future__ import annotations
+
+import secrets
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+from doppler_cli import blocks as block_registry
+from doppler_cli.ports import allocate
+from doppler_cli.state import BlockState, ChainState, stop_chain
+
+_CHAINS_DIR = Path.home() / ".doppler" / "chains"
+
+
+# ------------------------------------------------------------------
+# compose init
+# ------------------------------------------------------------------
+
+
+def init(
+    block_names: list[str],
+    out: Path | None = None,
+    name: str | None = None,
+) -> Path:
+    """Scaffold a compose file with defaults for the given block names.
+
+    The first block must be a source, the last a sink.  Ports are
+    auto-assigned and written into the file so it is fully explicit.
+
+    Parameters
+    ----------
+    block_names:
+        Ordered list of block names, e.g. ``["tone", "fir", "specan"]``.
+    out:
+        Path to write the compose file.  Defaults to
+        ``~/.doppler/chains/<ID>.yml``.
+    name:
+        Human-readable chain name / ID.  Used as the filename stem and
+        the ``id`` field in the compose file.  Defaults to a random
+        6-hex-digit ID.
+
+    Returns
+    -------
+    Path to the written compose file.
+    """
+    if len(block_names) < 2:
+        raise ValueError("Need at least a source and a sink.")
+
+    # Resolve block classes and build default configs
+    block_classes = [block_registry.get(n) for n in block_names]
+    configs = [cls.Config() for cls in block_classes]
+
+    # Validate roles
+    if block_classes[0].role != "source":
+        raise ValueError(
+            f"First block must be a source, got {block_names[0]!r} "
+            f"(role={block_classes[0].role!r})"
+        )
+    if block_classes[-1].role != "sink":
+        raise ValueError(
+            f"Last block must be a sink, got {block_names[-1]!r} "
+            f"(role={block_classes[-1].role!r})"
+        )
+
+    # Number of inter-block connections = number of non-sink blocks
+    n_ports = len(block_names) - 1
+    ports = allocate(n_ports)
+
+    chain_id = name or secrets.token_hex(3)  # e.g. "a3f7c2"
+
+    # Build YAML document
+    doc: dict = {"id": chain_id}
+
+    source_cfg = configs[0].model_dump()
+    source_cfg["port"] = ports[0]
+    doc["source"] = {"type": block_names[0], **source_cfg}
+
+    chain_blocks = []
+    for i, (name, cfg) in enumerate(zip(block_names[1:-1], configs[1:-1])):
+        entry = cfg.model_dump()
+        entry["port"] = ports[i + 1]
+        chain_blocks.append({name: entry})
+    if chain_blocks:
+        doc["chain"] = chain_blocks
+
+    sink_cfg = configs[-1].model_dump()
+    doc["sink"] = {"type": block_names[-1], **sink_cfg}
+
+    # Write file
+    if out is None:
+        _CHAINS_DIR.mkdir(parents=True, exist_ok=True)
+        out = _CHAINS_DIR / f"{chain_id}.yml"
+
+    out.write_text(yaml.dump(doc, default_flow_style=False, sort_keys=False))
+    return out
+
+
+# ------------------------------------------------------------------
+# compose up
+# ------------------------------------------------------------------
+
+
+def up(compose_file: Path) -> ChainState:
+    """Spawn all blocks described in *compose_file*.
+
+    Returns the ChainState (also persisted to ~/.doppler/chains/).
+    """
+    doc = yaml.safe_load(compose_file.read_text())
+    chain_id: str = doc.get("id") or secrets.token_hex(3)
+
+    source_doc = doc["source"]
+    source_type = source_doc.pop("type")
+    source_port: int = source_doc.pop("port")
+    source_addr = f"tcp://127.0.0.1:{source_port}"
+
+    chain_docs: list[dict] = doc.get("chain", [])
+    sink_doc = doc["sink"]
+    sink_type = sink_doc.pop("type")
+
+    block_states: list[BlockState] = []
+    _CHAINS_DIR.mkdir(parents=True, exist_ok=True)
+
+    def _spawn(name: str, cmd: list[str]) -> tuple[subprocess.Popen, str]:
+        log_path = _CHAINS_DIR / f"{chain_id}-{name}.log"
+        log_fh = open(log_path, "w")  # noqa: SIM115
+        proc = subprocess.Popen(  # noqa: S603
+            cmd, stdout=log_fh, stderr=log_fh
+        )
+        return proc, str(log_path)
+
+    # --- spawn source ---
+    src_cls = block_registry.get(source_type)
+    src_cfg = src_cls.Config(**source_doc)
+    src_cmd = src_cls().command(src_cfg, None, source_addr)
+    src_proc, src_log = _spawn(source_type, src_cmd)
+    block_states.append(
+        BlockState(
+            name=source_type,
+            pid=src_proc.pid,
+            bind_port=source_port,
+            log_file=src_log,
+        )
+    )
+
+    # --- spawn chain blocks ---
+    prev_addr = source_addr
+    for entry in chain_docs:
+        (name, cfg_dict) = next(iter(entry.items()))
+        out_port: int = cfg_dict.pop("port")
+        out_addr = f"tcp://127.0.0.1:{out_port}"
+        in_port = int(prev_addr.rsplit(":", 1)[-1])
+
+        blk_cls = block_registry.get(name)
+        blk_cfg = blk_cls.Config(**cfg_dict)
+        blk_cmd = blk_cls().command(blk_cfg, prev_addr, out_addr)
+        blk_proc, blk_log = _spawn(name, blk_cmd)
+        block_states.append(
+            BlockState(
+                name=name,
+                pid=blk_proc.pid,
+                connect_port=in_port,
+                bind_port=out_port,
+                log_file=blk_log,
+            )
+        )
+        prev_addr = out_addr
+
+    # --- spawn sink ---
+    sink_in_port = int(prev_addr.rsplit(":", 1)[-1])
+    snk_cls = block_registry.get(sink_type)
+    snk_cfg = snk_cls.Config(**sink_doc)
+    snk_cmd = snk_cls().command(snk_cfg, prev_addr, None)
+    snk_proc, snk_log = _spawn(sink_type, snk_cmd)
+    block_states.append(
+        BlockState(
+            name=sink_type,
+            pid=snk_proc.pid,
+            log_file=snk_log,
+            connect_port=sink_in_port,
+        )
+    )
+
+    state = ChainState(
+        id=chain_id,
+        started=datetime.now(timezone.utc).isoformat(),
+        compose=str(compose_file),
+        blocks=block_states,
+    )
+    state.save()
+    return state
+
+
+# ------------------------------------------------------------------
+# compose down
+# ------------------------------------------------------------------
+
+
+def down(chain_id: str, kill: bool = False) -> None:
+    """Stop all blocks in the chain identified by *chain_id*."""
+    from doppler_cli.state import ChainState  # noqa: PLC0415
+
+    chain = ChainState.load(chain_id)
+    stop_chain(chain, kill=kill)