swarph-cli 0.1.1__py3-none-any.whl

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+swarph_cli/__init__.py,sha256=2exfOKQZEUd0ziPGdrxWSZMG6EBPPhCaZa40hdBmdbU,678
+swarph_cli/caller.py,sha256=NKEbGkoyRf-BCdXzGwYzLsPnr6xgxRldRQbxTEcKHc0,1288
+swarph_cli/main.py,sha256=5CSNu4ENSYpG3aF5dOAW52fApuec1fwHB24dGhchkEo,7255
+swarph_cli-0.1.1.dist-info/licenses/LICENSE,sha256=PFBo9Jfj0JbAYTdIvxVWHbMac93_iM57n27yQs80BJ4,1086
+swarph_cli-0.1.1.dist-info/METADATA,sha256=3u6faTLas5BiT5CHTzHMQ733BkgmnPClBX3U_8YL4_M,4485
+swarph_cli-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+swarph_cli-0.1.1.dist-info/entry_points.txt,sha256=61jM-mwvdoN9FWnL5AgXxhmbJ39zhP-GsllJzsmRlF0,48
+swarph_cli-0.1.1.dist-info/top_level.txt,sha256=2sTqSJDjO0wW9xURA1IYlRD0kX_1qI0Sm5_rG8jhkQc,11
+swarph_cli-0.1.1.dist-info/RECORD,,

swarph_cli-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

swarph_cli-0.1.1.dist-info/entry_points.txt

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

swarph_cli-0.1.1.dist-info/licenses/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.dist-info/top_level.txt

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