swarph-cli 0.1.1__tar.gz

swarph_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pierre Samson and Claude Opus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swarph_cli-0.1.1/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: swarph-cli
+Version: 0.1.1
+Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. Phase 2 one-shot mode shipped (PLAN.md §13).
+Author: Pierre Samson, Claude Opus
+License: MIT
+Project-URL: Homepage, https://github.com/darw007d/swarph-cli
+Project-URL: Source, https://github.com/darw007d/swarph-cli
+Project-URL: Substrate, https://github.com/darw007d/swarph-mesh
+Project-URL: Spec, https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md
+Keywords: swarph,llm,cli,mesh,gemini,claude,deepseek
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: swarph-mesh>=0.1.0
+Requires-Dist: swarph-shared>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# swarph-cli
+
+The `swarph` binary — multi-LLM CLI with mesh-gateway integration. Thin client over the [`swarph-mesh`](https://github.com/darw007d/swarph-mesh) substrate.
+
+```bash
+pip install swarph-cli
+swarph --version
+```
+
+This is one of three repos in the v0.3.x architecture:
+
+| Repo | Role |
+|---|---|
+| [`swarph-mesh`](https://github.com/darw007d/swarph-mesh) | Substrate Python package — Protocol + adapters + SwarphCall + MeshClient. Pure library, no CLI |
+| [`swarph-cli`](https://github.com/darw007d/swarph-cli) | This repo — the `swarph` binary |
+| [`swarph-meshlm`](https://github.com/darw007d/swarph-meshlm) | Simon Willison `llm` plugin |
+
+## Status
+
+**v0.1.0 — Phase 2 one-shot mode.** The `swarph "prompt"` binary works end-to-end against `--provider gemini` per PLAN.md §13 falsifiability gate. Subsequent phases extend the CLI surface (REPL, `--ask <peer>`, onboard/ratify, daemon, import).
+
+```bash
+$ swarph "say pong" --provider gemini
+Pong!
+# 3+26t  $0.0000  0.73s  caller=cli.oneshot.ubuntu  provider=gemini
+```
+
+### `--json` mode semantics
+
+`--json` is a **harness trigger**, not a strict-validation gate. When set, swarph routes the response through the swarph-mesh JSON harness:
+
+- A permissive `{"type": "object"}` schema is synthesised when `--schema` is absent (Phase 5+ adds Pydantic validation).
+- The harness retries once with `[USER]`-turn feedback on parse failure.
+- **Malformed-JSON exits with code 1** + raw text on stdout for caller recovery. Useful for shell scripts:
+  ```bash
+  if swarph "give me a trade" --json; then
+    # parsed dict was on stdout
+    ...
+  fi
+  ```
+- Pretty-printed parsed dict on stdout when parse succeeds; `error_class=malformed_json` shows up in the stderr attribution footer when it doesn't.
+
+## Spec
+
+→ [hedge-fund-mcp / research/swarph_cli/PLAN.md](https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md)
+
+## Phase rollout
+
+| Phase | What lands |
+|---|---|
+| **0** (this) | Scaffold — entry-point + status banner |
+| **2** | One-shot mode: `swarph "hello" --provider gemini` |
+| **3** | `--ask <peer>` mesh-aware one-shot via MeshClient |
+| **5** | Interactive REPL — `/inbox`, `/reply`, `/dm`, `/watch` |
+| **5.5** | `swarph onboard <peer-name>` + `swarph ratify <peer-name>` (PLAN.md §15) |
+| **5.7** | `swarph daemon` foreground drain loop + `swarph chat` REPL with drain coroutine (PLAN.md §16) |
+| **6** | PyPI publish |
+
+## Why split CLI from substrate
+
+`swarph-mesh` (the library) is imported by `omega-boss`, Council judges, `lab-orchestrator`, and any future swarph peer that wants to write programs against the Protocol. Those callers don't need the CLI surface or the console-script entry point. Keeping the CLI in a separate repo means library users `pip install swarph-mesh` without pulling argparse + REPL plumbing they'll never run.
+
+## Install (dev)
+
+```bash
+git clone https://github.com/darw007d/swarph-cli
+cd swarph-cli
+python -m venv venv && source venv/bin/activate
+pip install -e ".[dev]"
+pytest
+swarph --version
+```
+
+## License
+
+MIT. Pierre Samson + Claude Opus, 2026.

swarph_cli-0.1.1/README.md

@@ -0,0 +1,76 @@
+# swarph-cli
+
+The `swarph` binary — multi-LLM CLI with mesh-gateway integration. Thin client over the [`swarph-mesh`](https://github.com/darw007d/swarph-mesh) substrate.
+
+```bash
+pip install swarph-cli
+swarph --version
+```
+
+This is one of three repos in the v0.3.x architecture:
+
+| Repo | Role |
+|---|---|
+| [`swarph-mesh`](https://github.com/darw007d/swarph-mesh) | Substrate Python package — Protocol + adapters + SwarphCall + MeshClient. Pure library, no CLI |
+| [`swarph-cli`](https://github.com/darw007d/swarph-cli) | This repo — the `swarph` binary |
+| [`swarph-meshlm`](https://github.com/darw007d/swarph-meshlm) | Simon Willison `llm` plugin |
+
+## Status
+
+**v0.1.0 — Phase 2 one-shot mode.** The `swarph "prompt"` binary works end-to-end against `--provider gemini` per PLAN.md §13 falsifiability gate. Subsequent phases extend the CLI surface (REPL, `--ask <peer>`, onboard/ratify, daemon, import).
+
+```bash
+$ swarph "say pong" --provider gemini
+Pong!
+# 3+26t  $0.0000  0.73s  caller=cli.oneshot.ubuntu  provider=gemini
+```
+
+### `--json` mode semantics
+
+`--json` is a **harness trigger**, not a strict-validation gate. When set, swarph routes the response through the swarph-mesh JSON harness:
+
+- A permissive `{"type": "object"}` schema is synthesised when `--schema` is absent (Phase 5+ adds Pydantic validation).
+- The harness retries once with `[USER]`-turn feedback on parse failure.
+- **Malformed-JSON exits with code 1** + raw text on stdout for caller recovery. Useful for shell scripts:
+  ```bash
+  if swarph "give me a trade" --json; then
+    # parsed dict was on stdout
+    ...
+  fi
+  ```
+- Pretty-printed parsed dict on stdout when parse succeeds; `error_class=malformed_json` shows up in the stderr attribution footer when it doesn't.
+
+## Spec
+
+→ [hedge-fund-mcp / research/swarph_cli/PLAN.md](https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md)
+
+## Phase rollout
+
+| Phase | What lands |
+|---|---|
+| **0** (this) | Scaffold — entry-point + status banner |
+| **2** | One-shot mode: `swarph "hello" --provider gemini` |
+| **3** | `--ask <peer>` mesh-aware one-shot via MeshClient |
+| **5** | Interactive REPL — `/inbox`, `/reply`, `/dm`, `/watch` |
+| **5.5** | `swarph onboard <peer-name>` + `swarph ratify <peer-name>` (PLAN.md §15) |
+| **5.7** | `swarph daemon` foreground drain loop + `swarph chat` REPL with drain coroutine (PLAN.md §16) |
+| **6** | PyPI publish |
+
+## Why split CLI from substrate
+
+`swarph-mesh` (the library) is imported by `omega-boss`, Council judges, `lab-orchestrator`, and any future swarph peer that wants to write programs against the Protocol. Those callers don't need the CLI surface or the console-script entry point. Keeping the CLI in a separate repo means library users `pip install swarph-mesh` without pulling argparse + REPL plumbing they'll never run.
+
+## Install (dev)
+
+```bash
+git clone https://github.com/darw007d/swarph-cli
+cd swarph-cli
+python -m venv venv && source venv/bin/activate
+pip install -e ".[dev]"
+pytest
+swarph --version
+```
+
+## License
+
+MIT. Pierre Samson + Claude Opus, 2026.

swarph_cli-0.1.1/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "swarph-cli"
+version = "0.1.1"
+description = "The `swarph` binary — multi-LLM CLI with mesh-gateway integration. Phase 2 one-shot mode shipped (PLAN.md §13)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Pierre Samson" },
+    { name = "Claude Opus" },
+]
+keywords = ["swarph", "llm", "cli", "mesh", "gemini", "claude", "deepseek"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "swarph-mesh>=0.1.0",
+    "swarph-shared>=0.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/darw007d/swarph-cli"
+Source = "https://github.com/darw007d/swarph-cli"
+Substrate = "https://github.com/darw007d/swarph-mesh"
+Spec = "https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+swarph = "swarph_cli.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"

swarph_cli-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

swarph_cli-0.1.1/src/swarph_cli/__init__.py

@@ -0,0 +1,21 @@
+"""swarph-cli — the ``swarph`` binary.
+
+Thin client over the ``swarph-mesh`` substrate. v0.0.1 ships the entry-
+point + a status banner. Live one-shot mode + REPL ship in Phase 2 / 5
+per PLAN.md §13.
+
+The architecture splits CLI from substrate so:
+
+* ``swarph-mesh`` stays a library importable from ``omega-boss``,
+  ``Council`` judges, ``lab-orchestrator``, etc. — no CLI surface or
+  console-script entry point required.
+* ``swarph-cli`` is a tiny argparse + REPL layer on top, ~200 LOC at
+  ship-out. Console users get the binary; library callers don't pull
+  in the CLI surface.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.1"
+
+__all__ = ["__version__"]

swarph_cli-0.1.1/src/swarph_cli/caller.py

@@ -0,0 +1,47 @@
+"""Build a default caller-convention slug for one-shot CLI invocations.
+
+Per swarph_shared.caller_convention the slug must match:
+
+    ^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$
+
+So we sanitize the OS username (which can have hyphens, capitals,
+digits-first, etc.) into a conformant fragment and prepend a fixed
+``cli.oneshot.`` prefix.
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+import re
+
+
+_NON_SLUG_CHARS = re.compile(r"[^a-z0-9_]+")
+
+
+def _sanitize_username(name: str) -> str:
+    """Turn an arbitrary username into a caller-convention fragment.
+
+    - Lowercase
+    - Replace any non-alnum/underscore with underscore
+    - Collapse runs of underscores
+    - Ensure leading char is a letter (prepend ``u_`` if not)
+    - Fall back to ``unknown`` if empty
+    """
+    s = name.lower()
+    s = _NON_SLUG_CHARS.sub("_", s)
+    s = re.sub(r"_+", "_", s).strip("_")
+    if not s:
+        return "unknown"
+    if not s[0].isalpha():
+        s = "u_" + s
+    return s
+
+
+def default_caller() -> str:
+    """Return ``cli.oneshot.<sanitized-user>`` for the current OS user."""
+    try:
+        user = getpass.getuser()
+    except Exception:
+        user = os.environ.get("USER") or os.environ.get("USERNAME") or "unknown"
+    return f"cli.oneshot.{_sanitize_username(user)}"

swarph_cli-0.1.1/src/swarph_cli/main.py

@@ -0,0 +1,223 @@
+"""``swarph`` entry-point — Phase 2 one-shot mode.
+
+v0.0.1 was the scaffold (banner-only). v0.1.0 ships the falsifiability
+gate from PLAN.md §13 Phase 2:
+
+    swarph "explain Hawkes process briefly" --provider gemini --model flash
+
+Subsequent phases extend the CLI:
+- Phase 3:    --ask <peer> mesh-aware one-shot via MeshClient
+- Phase 5:    interactive REPL (``swarph chat``)
+- Phase 5.5:  ``swarph onboard`` + ``swarph ratify``
+- Phase 5.7:  ``swarph daemon`` foreground drain
+- Phase 2.5:  ``swarph import --report-only`` per PLAN.md §17.6 reorder
+
+For now the entry-point handles ONE shape: positional prompt argument
++ provider/model flags + JSON-mode toggle. argparse subparsers will
+land in Phase 3 when more verbs need their own surface.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+from swarph_cli import __version__
+from swarph_cli.caller import default_caller
+
+
+_BANNER = """\
+swarph v{version}
+
+Usage:
+  swarph "your prompt here" [--provider gemini] [--model gemini-2.5-flash]
+
+Examples:
+  swarph "explain Hawkes process briefly"
+  swarph "list 5 tickers" --json
+  swarph "summarise" --provider gemini --model gemini-2.5-pro
+
+Status: Phase 2 one-shot mode. REPL (Phase 5), --ask <peer>
+(Phase 3), onboard/ratify (Phase 5.5), daemon (Phase 5.7) and
+import (Phase 2.5) ship in subsequent releases.
+
+Spec: https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md
+"""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="swarph",
+        description=(
+            "swarph — multi-LLM CLI with mesh-gateway integration. "
+            "Phase 2 one-shot mode."
+        ),
+    )
+    p.add_argument(
+        "prompt",
+        nargs="?",
+        default=None,
+        help='Prompt to send (one-shot mode). Omit to print a usage banner.',
+    )
+    p.add_argument(
+        "--provider",
+        default="gemini",
+        help='LLM provider. Phase 1 ships "gemini" only; Phase 4+ adds '
+        "deepseek/claude/openai/grok.",
+    )
+    p.add_argument(
+        "--model",
+        default=None,
+        help="Provider-specific model id. Defaults to the adapter's default_model.",
+    )
+    p.add_argument(
+        "--caller",
+        default=None,
+        help='Caller-convention slug (dotted lowercase). Defaults to '
+        '"cli.oneshot.<user>" for the current OS user.',
+    )
+    p.add_argument(
+        "--system",
+        default=None,
+        help="System prompt prepended to the conversation.",
+    )
+    p.add_argument(
+        "--temperature",
+        type=float,
+        default=0.7,
+        help="Sampling temperature (default 0.7).",
+    )
+    p.add_argument(
+        "--max-tokens",
+        type=int,
+        default=None,
+        help="Max output tokens (provider default if omitted).",
+    )
+    p.add_argument(
+        "--json",
+        action="store_true",
+        help="Parse response as JSON (TRIGGER for the swarph-mesh JSON "
+        "harness — not strict-validation; a permissive {'type': 'object'} "
+        "schema is synthesised when --schema is absent). Malformed-JSON "
+        "responses cause exit code 1 with raw text on stdout for caller "
+        "recovery — useful for shell scripts gating on "
+        "`if swarph 'x' --json; then ...`. Full Pydantic validation lands "
+        "in Phase 5+.",
+    )
+    p.add_argument(
+        "--schema",
+        default=None,
+        help="Path to a JSON Schema file. Implies --json. v0.1.0 uses the "
+        "schema only as the harness trigger; full Pydantic validation lands "
+        "in Phase 5+.",
+    )
+    p.add_argument(
+        "--quiet",
+        "-q",
+        action="store_true",
+        help="Suppress the per-call attribution footer on stderr.",
+    )
+    p.add_argument(
+        "--version",
+        action="version",
+        version=f"swarph-cli {__version__}",
+    )
+    return p
+
+
+def _print_banner() -> int:
+    print(_BANNER.format(version=__version__), file=sys.stderr)
+    return 0
+
+
+def _load_schema(path: Optional[str]) -> Optional[dict]:
+    if not path:
+        return None
+    p = Path(path)
+    if not p.exists():
+        print(f"swarph: --schema file not found: {path}", file=sys.stderr)
+        sys.exit(2)
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"swarph: --schema file is not valid JSON: {exc}", file=sys.stderr)
+        sys.exit(2)
+
+
+async def _run_one_shot(args: argparse.Namespace) -> int:
+    # Local import so unit tests of the CLI shape don't drag in the
+    # full SwarphCall wiring + Gemini SDK on import.
+    from swarph_mesh import ChatMessage, SwarphCall
+
+    caller = args.caller or default_caller()
+    json_schema = _load_schema(args.schema) or ({"type": "object"} if args.json else None)
+
+    try:
+        # SwarphCall construction enforces caller convention via
+        # swarph_shared.validate_caller — raises ValueError on
+        # invalid slugs. Keep inside try/except so a bad --caller
+        # argument exits 1 with a friendly error rather than dumps
+        # a traceback.
+        sc = SwarphCall(
+            provider=args.provider,
+            caller=caller,
+            model=args.model,
+        )
+        resp = await sc.chat(
+            messages=[ChatMessage(role="user", content=args.prompt)],
+            system_prompt=args.system,
+            json_schema=json_schema,
+            temperature=args.temperature,
+            max_tokens=args.max_tokens,
+        )
+    except Exception as exc:
+        print(f"swarph: call failed: {exc}", file=sys.stderr)
+        return 1
+
+    # JSON mode prints parsed dict (pretty) when available; falls back
+    # to raw text + error_class footer when the harness couldn't parse.
+    if json_schema is not None and resp.parsed is not None:
+        print(json.dumps(resp.parsed, indent=2, sort_keys=True))
+    else:
+        print(resp.text)
+
+    if not args.quiet:
+        # ``$0`` displays the subscription-path / free-tier case
+        # (adapter returns exactly 0.0); ``$0.0000`` displays a
+        # tiny-but-real API cost. Future adapters that introduce
+        # float drift around zero (e.g., 1e-12 due to multiplier
+        # rounding) would flip the display spuriously to
+        # ``$0.0000`` — audit + tighten the threshold if that bites
+        # (drop PR #1 review observation #2, DM #681).
+        cost_str = f"${resp.cost_usd:.4f}" if resp.cost_usd > 0 else "$0"
+        attribution = (
+            f"# {resp.input_tokens}+{resp.output_tokens}t  "
+            f"{cost_str}  {resp.duration_s:.2f}s  caller={caller}  "
+            f"provider={args.provider}"
+        )
+        if resp.cached:
+            attribution += "  (cached)"
+        if resp.error_class:
+            attribution += f"  error_class={resp.error_class}"
+        print(attribution, file=sys.stderr)
+
+    return 0 if resp.error_class is None else 1
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.prompt is None:
+        return _print_banner()
+
+    return asyncio.run(_run_one_shot(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

swarph_cli-0.1.1/src/swarph_cli.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: swarph-cli
+Version: 0.1.1
+Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. Phase 2 one-shot mode shipped (PLAN.md §13).
+Author: Pierre Samson, Claude Opus
+License: MIT
+Project-URL: Homepage, https://github.com/darw007d/swarph-cli
+Project-URL: Source, https://github.com/darw007d/swarph-cli
+Project-URL: Substrate, https://github.com/darw007d/swarph-mesh
+Project-URL: Spec, https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md
+Keywords: swarph,llm,cli,mesh,gemini,claude,deepseek
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: swarph-mesh>=0.1.0
+Requires-Dist: swarph-shared>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# swarph-cli
+
+The `swarph` binary — multi-LLM CLI with mesh-gateway integration. Thin client over the [`swarph-mesh`](https://github.com/darw007d/swarph-mesh) substrate.
+
+```bash
+pip install swarph-cli
+swarph --version
+```
+
+This is one of three repos in the v0.3.x architecture:
+
+| Repo | Role |
+|---|---|
+| [`swarph-mesh`](https://github.com/darw007d/swarph-mesh) | Substrate Python package — Protocol + adapters + SwarphCall + MeshClient. Pure library, no CLI |
+| [`swarph-cli`](https://github.com/darw007d/swarph-cli) | This repo — the `swarph` binary |
+| [`swarph-meshlm`](https://github.com/darw007d/swarph-meshlm) | Simon Willison `llm` plugin |
+
+## Status
+
+**v0.1.0 — Phase 2 one-shot mode.** The `swarph "prompt"` binary works end-to-end against `--provider gemini` per PLAN.md §13 falsifiability gate. Subsequent phases extend the CLI surface (REPL, `--ask <peer>`, onboard/ratify, daemon, import).
+
+```bash
+$ swarph "say pong" --provider gemini
+Pong!
+# 3+26t  $0.0000  0.73s  caller=cli.oneshot.ubuntu  provider=gemini
+```
+
+### `--json` mode semantics
+
+`--json` is a **harness trigger**, not a strict-validation gate. When set, swarph routes the response through the swarph-mesh JSON harness:
+
+- A permissive `{"type": "object"}` schema is synthesised when `--schema` is absent (Phase 5+ adds Pydantic validation).
+- The harness retries once with `[USER]`-turn feedback on parse failure.
+- **Malformed-JSON exits with code 1** + raw text on stdout for caller recovery. Useful for shell scripts:
+  ```bash
+  if swarph "give me a trade" --json; then
+    # parsed dict was on stdout
+    ...
+  fi
+  ```
+- Pretty-printed parsed dict on stdout when parse succeeds; `error_class=malformed_json` shows up in the stderr attribution footer when it doesn't.
+
+## Spec
+
+→ [hedge-fund-mcp / research/swarph_cli/PLAN.md](https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md)
+
+## Phase rollout
+
+| Phase | What lands |
+|---|---|
+| **0** (this) | Scaffold — entry-point + status banner |
+| **2** | One-shot mode: `swarph "hello" --provider gemini` |
+| **3** | `--ask <peer>` mesh-aware one-shot via MeshClient |
+| **5** | Interactive REPL — `/inbox`, `/reply`, `/dm`, `/watch` |
+| **5.5** | `swarph onboard <peer-name>` + `swarph ratify <peer-name>` (PLAN.md §15) |
+| **5.7** | `swarph daemon` foreground drain loop + `swarph chat` REPL with drain coroutine (PLAN.md §16) |
+| **6** | PyPI publish |
+
+## Why split CLI from substrate
+
+`swarph-mesh` (the library) is imported by `omega-boss`, Council judges, `lab-orchestrator`, and any future swarph peer that wants to write programs against the Protocol. Those callers don't need the CLI surface or the console-script entry point. Keeping the CLI in a separate repo means library users `pip install swarph-mesh` without pulling argparse + REPL plumbing they'll never run.
+
+## Install (dev)
+
+```bash
+git clone https://github.com/darw007d/swarph-cli
+cd swarph-cli
+python -m venv venv && source venv/bin/activate
+pip install -e ".[dev]"
+pytest
+swarph --version
+```
+
+## License
+
+MIT. Pierre Samson + Claude Opus, 2026.

swarph_cli-0.1.1/src/swarph_cli.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/swarph_cli/__init__.py
+src/swarph_cli/caller.py
+src/swarph_cli/main.py
+src/swarph_cli.egg-info/PKG-INFO
+src/swarph_cli.egg-info/SOURCES.txt
+src/swarph_cli.egg-info/dependency_links.txt
+src/swarph_cli.egg-info/entry_points.txt
+src/swarph_cli.egg-info/requires.txt
+src/swarph_cli.egg-info/top_level.txt
+tests/test_main.py
+tests/test_smoke_one_shot.py

swarph_cli-0.1.1/src/swarph_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

swarph_cli-0.1.1/src/swarph_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+swarph = swarph_cli.main:main

swarph_cli-0.1.1/src/swarph_cli.egg-info/requires.txt

@@ -0,0 +1,5 @@
+swarph-mesh>=0.1.0
+swarph-shared>=0.2.0
+
+[dev]
+pytest>=7.0

swarph_cli-0.1.1/src/swarph_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+swarph_cli

swarph_cli-0.1.1/tests/test_main.py

@@ -0,0 +1,371 @@
+"""Phase 2 one-shot CLI tests.
+
+Most tests run offline using a mock adapter registered against
+swarph-mesh's adapter registry — same pattern as swarph-mesh's
+test_swarph_call. The live falsifiability gate (real Gemini API)
+lives in test_smoke_one_shot.py and is skipped without
+GEMINI_API_KEY.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import AsyncIterator, Optional
+from unittest.mock import patch
+
+import pytest
+
+from swarph_cli import __version__
+from swarph_cli.caller import _sanitize_username, default_caller
+from swarph_cli.main import _build_parser, main
+
+
+# ---------------------------------------------------------------------------
+# Fixtures — register a mock adapter so the CLI's SwarphCall path runs offline
+# ---------------------------------------------------------------------------
+
+
+class _MockAdapter:
+    name = "mock"
+    default_model = "mock-model-v1"
+
+    def __init__(self, text="ok", input_tokens=10, output_tokens=5, cost_usd=0.001):
+        self.text = text
+        self.input_tokens = input_tokens
+        self.output_tokens = output_tokens
+        self.cost_usd = cost_usd
+        self.calls = []
+
+    async def chat(self, messages, model, **kwargs):
+        from swarph_mesh import LLMResponse
+
+        self.calls.append({"messages": list(messages), "model": model, **kwargs})
+        return LLMResponse(
+            text=self.text,
+            input_tokens=self.input_tokens,
+            output_tokens=self.output_tokens,
+            cost_usd=self.cost_usd,
+            duration_s=0.05,
+        )
+
+    async def stream(self, *a, **kw) -> AsyncIterator[str]:
+        if False:
+            yield ""
+
+    def cost_per_token(self, model):
+        return (0.0, 0.0)
+
+
+@pytest.fixture
+def mock_adapter(tmp_path):
+    """Register a mock adapter as 'mock' AND swap the default
+    attribution writer to a tmp file so tests don't pollute
+    ~/.swarph/attribution.jsonl."""
+    from swarph_mesh import register_adapter
+    from swarph_mesh.adapters import reset_registry
+    from swarph_mesh.attribution import (
+        FileAttributionWriter,
+        NullAttributionWriter,
+        set_default_writer,
+    )
+
+    reset_registry()
+    a = _MockAdapter()
+    register_adapter("mock", a)
+    set_default_writer(FileAttributionWriter(path=tmp_path / "attribution.jsonl"))
+    yield a
+    reset_registry()
+    set_default_writer(NullAttributionWriter())
+
+
+# ---------------------------------------------------------------------------
+# Caller helper
+# ---------------------------------------------------------------------------
+
+
+def test_default_caller_starts_with_cli_oneshot():
+    c = default_caller()
+    assert c.startswith("cli.oneshot.")
+    # Must satisfy the swarph_shared CALLER_PATTERN regex:
+    from swarph_shared import validate_caller
+
+    validate_caller(c)
+
+
+def test_sanitize_username_handles_capitals():
+    assert _sanitize_username("Alice") == "alice"
+
+
+def test_sanitize_username_handles_hyphens():
+    assert _sanitize_username("alice-bob") == "alice_bob"
+
+
+def test_sanitize_username_handles_digits_first():
+    assert _sanitize_username("42alice") == "u_42alice"
+
+
+def test_sanitize_username_handles_empty():
+    assert _sanitize_username("") == "unknown"
+
+
+def test_sanitize_username_handles_special_chars():
+    assert _sanitize_username("a!b@c#d") == "a_b_c_d"
+
+
+# ---------------------------------------------------------------------------
+# argparse — flag parsing
+# ---------------------------------------------------------------------------
+
+
+def test_parser_handles_positional_prompt():
+    args = _build_parser().parse_args(["hello world"])
+    assert args.prompt == "hello world"
+    assert args.provider == "gemini"  # default
+
+
+def test_parser_handles_provider_flag():
+    args = _build_parser().parse_args(["x", "--provider", "claude"])
+    assert args.provider == "claude"
+
+
+def test_parser_handles_json_flag():
+    args = _build_parser().parse_args(["x", "--json"])
+    assert args.json is True
+
+
+def test_parser_handles_quiet_flag():
+    args = _build_parser().parse_args(["-q", "x"])
+    assert args.quiet is True
+
+
+def test_parser_no_prompt_returns_none():
+    """Empty argv → prompt is None → main() prints banner."""
+    args = _build_parser().parse_args([])
+    assert args.prompt is None
+
+
+# ---------------------------------------------------------------------------
+# Banner mode (no prompt)
+# ---------------------------------------------------------------------------
+
+
+def test_main_no_prompt_prints_banner_exits_zero(capsys):
+    rc = main(argv=[])
+    assert rc == 0
+    captured = capsys.readouterr()
+    assert "swarph" in captured.err
+    assert __version__ in captured.err
+    assert "Phase 2" in captured.err
+
+
+# ---------------------------------------------------------------------------
+# One-shot — adapter dispatch + stdout/stderr split
+# ---------------------------------------------------------------------------
+
+
+def test_one_shot_invokes_adapter_with_prompt(mock_adapter, capsys):
+    rc = main(argv=["--provider", "mock", "hello"])
+    assert rc == 0
+    assert len(mock_adapter.calls) == 1
+    assert mock_adapter.calls[0]["messages"][0].content == "hello"
+
+
+def test_one_shot_response_text_to_stdout(mock_adapter, capsys):
+    mock_adapter.text = "the response"
+    rc = main(argv=["--provider", "mock", "x"])
+    captured = capsys.readouterr()
+    assert "the response" in captured.out
+    # Attribution footer should NOT be on stdout
+    assert "+" not in captured.out
+    assert "USD" not in captured.out
+    # Attribution footer SHOULD be on stderr
+    assert "10+5t" in captured.err  # input_tokens + output_tokens
+    assert "$0.0010" in captured.err
+    assert "caller=cli.oneshot." in captured.err
+    assert "provider=mock" in captured.err
+
+
+def test_one_shot_quiet_suppresses_attribution(mock_adapter, capsys):
+    rc = main(argv=["--quiet", "--provider", "mock", "x"])
+    captured = capsys.readouterr()
+    assert "the response" not in captured.err  # no attribution at all
+    assert "10+5t" not in captured.err
+
+
+def test_one_shot_passes_temperature(mock_adapter, capsys):
+    main(argv=["--provider", "mock", "--temperature", "0.1", "x"])
+    assert mock_adapter.calls[0]["temperature"] == pytest.approx(0.1)
+
+
+def test_one_shot_passes_system_prompt(mock_adapter, capsys):
+    main(argv=["--provider", "mock", "--system", "be terse", "x"])
+    assert mock_adapter.calls[0]["system_prompt"] == "be terse"
+
+
+def test_one_shot_passes_max_tokens(mock_adapter, capsys):
+    main(argv=["--provider", "mock", "--max-tokens", "256", "x"])
+    assert mock_adapter.calls[0]["max_tokens"] == 256
+
+
+def test_one_shot_uses_explicit_model(mock_adapter, capsys):
+    main(argv=["--provider", "mock", "--model", "override", "x"])
+    assert mock_adapter.calls[0]["model"] == "override"
+
+
+def test_one_shot_uses_explicit_caller(mock_adapter, capsys):
+    main(argv=["--provider", "mock", "--caller", "test.suite.explicit", "x"])
+    captured = capsys.readouterr()
+    assert "caller=test.suite.explicit" in captured.err
+
+
+def test_one_shot_invalid_caller_exits_nonzero(mock_adapter, capsys):
+    """Caller convention enforced at SwarphCall construction (via
+    swarph_shared.validate_caller) — invalid callers fail loud.
+
+    main() catches the ValueError in _run_one_shot's try/except and
+    returns 1.
+    """
+    rc = main(argv=["--provider", "mock", "--caller", "Invalid!", "x"])
+    assert rc == 1
+    captured = capsys.readouterr()
+    assert "swarph: call failed:" in captured.err
+
+
+# ---------------------------------------------------------------------------
+# JSON mode
+# ---------------------------------------------------------------------------
+
+
+def test_json_flag_pretty_prints_parsed_dict(mock_adapter, capsys):
+    mock_adapter.text = '{"action": "BUY", "ticker": "MSFT"}'
+    rc = main(argv=["--provider", "mock", "--json", "give me a trade"])
+    assert rc == 0
+    captured = capsys.readouterr()
+    # Pretty-printed (indented) JSON on stdout
+    assert '"action": "BUY"' in captured.out
+    assert '"ticker": "MSFT"' in captured.out
+
+
+def test_json_flag_falls_back_to_raw_on_parse_fail(mock_adapter, capsys):
+    """When json mode is on but the harness couldn't parse, exit 1
+    + print raw text to stdout so the caller can recover."""
+    mock_adapter.text = "this is just prose, no json"
+    rc = main(argv=["--provider", "mock", "--json", "x"])
+    assert rc == 1
+    captured = capsys.readouterr()
+    # Raw text printed on stdout for caller recovery
+    assert "this is just prose" in captured.out
+    # error_class shows up in attribution footer
+    assert "error_class=malformed_json" in captured.err
+
+
+def test_schema_path_loads_json_file(mock_adapter, capsys, tmp_path):
+    schema_file = tmp_path / "schema.json"
+    schema_file.write_text(json.dumps({"type": "object", "required": ["x"]}))
+    mock_adapter.text = '{"x": 1}'
+    rc = main(argv=[
+        "--provider", "mock",
+        "--schema", str(schema_file),
+        "give me an object",
+    ])
+    assert rc == 0
+
+
+def test_schema_missing_file_exits_2(mock_adapter, capsys, tmp_path):
+    """Missing schema file should fail loud BEFORE any LLM call."""
+    bogus = str(tmp_path / "does-not-exist.json")
+    with pytest.raises(SystemExit) as excinfo:
+        main(argv=["--provider", "mock", "--schema", bogus, "x"])
+    assert excinfo.value.code == 2
+
+
+def test_schema_invalid_json_exits_2(mock_adapter, capsys, tmp_path):
+    bad_schema = tmp_path / "bad.json"
+    bad_schema.write_text("{not valid")
+    with pytest.raises(SystemExit) as excinfo:
+        main(argv=["--provider", "mock", "--schema", str(bad_schema), "x"])
+    assert excinfo.value.code == 2
+
+
+# ---------------------------------------------------------------------------
+# Adapter error handling
+# ---------------------------------------------------------------------------
+
+
+def test_adapter_error_returns_nonzero(capsys):
+    """Adapter raising → exit code 1 + error message on stderr."""
+    from swarph_mesh import register_adapter
+    from swarph_mesh.adapters import reset_registry
+
+    class _BrokenAdapter:
+        name = "broken"
+        default_model = "broken-v1"
+
+        async def chat(self, *a, **kw):
+            raise RuntimeError("provider down")
+
+        async def stream(self, *a, **kw):
+            if False:
+                yield ""
+
+        def cost_per_token(self, model):
+            return (0.0, 0.0)
+
+    reset_registry()
+    register_adapter("broken", _BrokenAdapter())
+    try:
+        rc = main(argv=["--provider", "broken", "x"])
+        assert rc == 1
+        captured = capsys.readouterr()
+        assert "swarph: call failed:" in captured.err
+        assert "provider down" in captured.err
+    finally:
+        reset_registry()
+
+
+# ---------------------------------------------------------------------------
+# Subprocess invocation — verifies the entry-point script wiring
+# ---------------------------------------------------------------------------
+
+
+def test_version_flag_via_subprocess():
+    result = subprocess.run(
+        [sys.executable, "-m", "swarph_cli.main", "--version"],
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    assert result.returncode == 0
+    assert __version__ in result.stdout
+
+
+def test_no_args_subprocess_prints_banner():
+    result = subprocess.run(
+        [sys.executable, "-m", "swarph_cli.main"],
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    assert result.returncode == 0
+    assert "swarph" in result.stderr
+
+
+# ---------------------------------------------------------------------------
+# swarph-mesh + swarph-shared deps still resolvable (carry-forward from v0.0.1)
+# ---------------------------------------------------------------------------
+
+
+def test_swarph_mesh_dep_resolvable():
+    import swarph_mesh
+
+    assert hasattr(swarph_mesh, "SwarphCall")
+    assert hasattr(swarph_mesh, "ChatMessage")
+
+
+def test_swarph_shared_dep_resolvable():
+    import swarph_shared
+
+    assert hasattr(swarph_shared, "validate_node_name")

swarph_cli-0.1.1/tests/test_smoke_one_shot.py

@@ -0,0 +1,57 @@
+"""Live smoke test for Phase 2 one-shot CLI — falsifiability gate
+per PLAN.md §13:
+
+    swarph "hello" --provider gemini  →  text on stdout, attribution
+                                          footer on stderr, exit 0
+
+Gated on ``GEMINI_API_KEY`` being set in the environment. Skipped
+on CI without the key.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+import pytest
+
+pytestmark = pytest.mark.skipif(
+    not os.environ.get("GEMINI_API_KEY"),
+    reason="GEMINI_API_KEY not set; live smoke test skipped",
+)
+
+
+def test_phase_2_falsifiability_gate():
+    """Run the actual ``swarph`` binary as a subprocess against real
+    Gemini API. Verifies the entry-point is wired end-to-end:
+
+    - argparse → SwarphCall → GeminiAdapter → real API
+    - response text printed to stdout
+    - attribution footer printed to stderr
+    - exit code 0
+    """
+    result = subprocess.run(
+        [sys.executable, "-m", "swarph_cli.main",
+         "--provider", "gemini",
+         "say 'pong' and nothing else"],
+        capture_output=True,
+        text=True,
+        timeout=60,
+        env={**os.environ},  # preserve GEMINI_API_KEY
+    )
+
+    assert result.returncode == 0, (
+        f"swarph exited {result.returncode}.\n"
+        f"stdout={result.stdout!r}\nstderr={result.stderr!r}"
+    )
+
+    # Response text on stdout
+    assert result.stdout.strip()  # non-empty
+    assert "pong" in result.stdout.lower()
+
+    # Attribution footer on stderr
+    assert "+" in result.stderr  # the input+output token marker
+    assert "$" in result.stderr  # cost
+    assert "caller=cli.oneshot." in result.stderr
+    assert "provider=gemini" in result.stderr