spawnllm 0.1.0__tar.gz

spawnllm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yasyf Mohamedali
+
+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.

spawnllm-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: spawnllm
+Version: 0.1.0
+Summary: Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
+Keywords: 
+Author: Yasyf Mohamedali
+Author-email: Yasyf Mohamedali <yasyfm@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Dist: click>=8
+Requires-Dist: loguru>=0.7
+Requires-Dist: pydantic>=2
+Requires-Dist: zstandard>=0.25.0 ; extra == 'adapter'
+Requires-Dist: numpy>=1.26 ; extra == 'adapter'
+Requires-Dist: orjson>=3.10 ; extra == 'adapter'
+Requires-Dist: anyio>=4 ; extra == 'dev'
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.8 ; extra == 'dev'
+Requires-Dist: ty>=0.0.44 ; extra == 'dev'
+Requires-Dist: zstandard>=0.25.0 ; extra == 'dev'
+Requires-Dist: numpy>=1.26 ; extra == 'dev'
+Requires-Dist: orjson>=3.10 ; extra == 'dev'
+Requires-Dist: zstandard>=0.25.0 ; extra == 'mlx'
+Requires-Dist: numpy>=1.26 ; extra == 'mlx'
+Requires-Dist: orjson>=3.10 ; extra == 'mlx'
+Requires-Dist: anyio>=4.4 ; extra == 'mlx'
+Requires-Dist: huggingface-hub>=0.25 ; extra == 'mlx'
+Requires-Dist: mlx-lm>=0.31.3 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'mlx'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/yasyf/spawnllm
+Project-URL: Documentation, https://yasyf.github.io/spawnllm/
+Project-URL: Repository, https://github.com/yasyf/spawnllm
+Project-URL: Issues, https://github.com/yasyf/spawnllm/issues
+Project-URL: Changelog, https://github.com/yasyf/spawnllm/blob/main/CHANGELOG.md
+Provides-Extra: adapter
+Provides-Extra: dev
+Provides-Extra: mlx
+Description-Content-Type: text/markdown
+
+# spawnllm
+
+[![PyPI](https://img.shields.io/pypi/v/spawnllm.svg)](https://pypi.org/project/spawnllm/)
+[![Python](https://img.shields.io/pypi/pyversions/spawnllm.svg)](https://pypi.org/project/spawnllm/)
+[![Docs](https://img.shields.io/github/actions/workflow/status/yasyf/spawnllm/docs.yml?branch=main&label=docs)](https://yasyf.github.io/spawnllm/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/yasyf/spawnllm/blob/main/LICENSE)
+
+Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
+
+spawnllm centralizes the LLM-calling plumbing that small tools keep re-inventing: driving the
+`claude` and `codex` CLIs as subshells — with structured Pydantic output, model tiers, and
+faithful error capture — and running local Apple-Silicon MLX models with adapter fusion,
+prompt-cache reuse, and batched generation. Depend on it once and each tool keeps only its
+domain logic instead of its own copy of the backends.
+
+## Install
+
+No install needed — run everything through [uvx](https://docs.astral.sh/uv/):
+
+```bash
+uvx spawnllm --help
+```
+
+`uvx` fetches spawnllm into a throwaway environment and runs it. To add it
+to a project instead:
+
+```bash
+uv add spawnllm
+```
+
+For the local MLX engine (Apple Silicon only), pull the extra:
+
+```bash
+uv add "spawnllm[mlx]"
+```
+
+## Quickstart
+
+List the backends spawnllm can drive:
+
+```bash
+uvx spawnllm backends
+```
+
+```
+claude
+codex
+mlx
+```
+
+## What problems does this solve?
+
+- **Duplicate subshell plumbing.** Building `claude`/`codex` argv, piping stdin/stdout, teeing
+  stderr, and turning non-zero exits into useful errors — written once, not re-derived per tool.
+- **Structured-output boilerplate.** A Pydantic model becomes a JSON-schema constraint and a
+  parsed, validated result the same way for every backend.
+- **Local MLX is fiddly.** Adapter fusion, prompt-cache reuse, worker-thread lifecycle, and
+  batched single-token generation live behind one engine instead of in every consumer.
+- **Behavior drift.** Two tools that call the same models stay byte-for-byte consistent because
+  they share the backend layer rather than each maintaining a copy.
+
+## Docs
+
+[Read the docs](https://yasyf.github.io/spawnllm/) for the full guide and API reference.

spawnllm-0.1.0/README.md

@@ -0,0 +1,64 @@
+# spawnllm
+
+[![PyPI](https://img.shields.io/pypi/v/spawnllm.svg)](https://pypi.org/project/spawnllm/)
+[![Python](https://img.shields.io/pypi/pyversions/spawnllm.svg)](https://pypi.org/project/spawnllm/)
+[![Docs](https://img.shields.io/github/actions/workflow/status/yasyf/spawnllm/docs.yml?branch=main&label=docs)](https://yasyf.github.io/spawnllm/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/yasyf/spawnllm/blob/main/LICENSE)
+
+Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
+
+spawnllm centralizes the LLM-calling plumbing that small tools keep re-inventing: driving the
+`claude` and `codex` CLIs as subshells — with structured Pydantic output, model tiers, and
+faithful error capture — and running local Apple-Silicon MLX models with adapter fusion,
+prompt-cache reuse, and batched generation. Depend on it once and each tool keeps only its
+domain logic instead of its own copy of the backends.
+
+## Install
+
+No install needed — run everything through [uvx](https://docs.astral.sh/uv/):
+
+```bash
+uvx spawnllm --help
+```
+
+`uvx` fetches spawnllm into a throwaway environment and runs it. To add it
+to a project instead:
+
+```bash
+uv add spawnllm
+```
+
+For the local MLX engine (Apple Silicon only), pull the extra:
+
+```bash
+uv add "spawnllm[mlx]"
+```
+
+## Quickstart
+
+List the backends spawnllm can drive:
+
+```bash
+uvx spawnllm backends
+```
+
+```
+claude
+codex
+mlx
+```
+
+## What problems does this solve?
+
+- **Duplicate subshell plumbing.** Building `claude`/`codex` argv, piping stdin/stdout, teeing
+  stderr, and turning non-zero exits into useful errors — written once, not re-derived per tool.
+- **Structured-output boilerplate.** A Pydantic model becomes a JSON-schema constraint and a
+  parsed, validated result the same way for every backend.
+- **Local MLX is fiddly.** Adapter fusion, prompt-cache reuse, worker-thread lifecycle, and
+  batched single-token generation live behind one engine instead of in every consumer.
+- **Behavior drift.** Two tools that call the same models stay byte-for-byte consistent because
+  they share the backend layer rather than each maintaining a copy.
+
+## Docs
+
+[Read the docs](https://yasyf.github.io/spawnllm/) for the full guide and API reference.

spawnllm-0.1.0/pyproject.toml

@@ -0,0 +1,129 @@
+[project]
+name = "spawnllm"
+version = "0.1.0"
+description = "Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Yasyf Mohamedali", email = "yasyfm@gmail.com" }]
+keywords = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+requires-python = ">=3.13"
+dependencies = [
+    "click>=8",
+    "loguru>=0.7",
+    "pydantic>=2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "anyio>=4",
+    "pytest>=8.0",
+    "ruff>=0.8",
+    "ty>=0.0.44",
+    # Codec tests exercise zstandard/numpy/orjson.
+    "zstandard>=0.25.0",
+    "numpy>=1.26",
+    "orjson>=3.10",
+]
+# Cross-platform LoRA adapter codec (zstd + numpy); imported without mlx.
+adapter = [
+    "zstandard>=0.25.0",
+    "numpy>=1.26",
+    "orjson>=3.10",
+]
+# Local Apple-Silicon MLX engine. mlx-lm carries the darwin/arm64 marker; the
+# codec libs and anyio are cross-platform but only meaningful alongside it.
+mlx = [
+    "zstandard>=0.25.0",
+    "numpy>=1.26",
+    "orjson>=3.10",
+    "anyio>=4.4",
+    "huggingface-hub>=0.25",
+    "mlx-lm>=0.31.3; sys_platform == 'darwin' and platform_machine == 'arm64'",
+]
+
+[project.scripts]
+spawnllm = "spawnllm.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/yasyf/spawnllm"
+Documentation = "https://yasyf.github.io/spawnllm/"
+Repository = "https://github.com/yasyf/spawnllm"
+Issues = "https://github.com/yasyf/spawnllm/issues"
+Changelog = "https://github.com/yasyf/spawnllm/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "spawnllm"
+module-root = ""
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+anyio_mode = "auto"
+addopts = ["-ra", "--strict-markers", "--tb=short", "-q"]
+markers = [
+    "unit: Pure unit tests",
+    "integration: Integration tests",
+]
+
+# ty (Astral) is the default type checker — run `uv run ty check spawnllm`.
+# It is fast, understands modern syntax, and avoids the strict-pyright false
+# positives on pydantic/attrs-style dynamic defaults and PK-type overrides.
+[tool.ty.rules]
+# Keep cross-checker `# type: ignore` / `# pyright: ignore` comments from tripping ty.
+unused-type-ignore-comment = "ignore"
+# The MLX engine lazily imports optional native deps (mlx_lm, mlx, huggingface_hub)
+# that are absent off Apple Silicon and in the dev/CI environment.
+unresolved-import = "ignore"
+
+# pyright is kept as a secondary checker (editors / `uvx pyright`). Basic mode plus
+# a few disables covers the noise; ty is the gate that runs in CI.
+[tool.pyright]
+pythonVersion = "3.13"
+typeCheckingMode = "basic"
+include = ["spawnllm"]
+venvPath = "."
+venv = ".venv"
+reportImplicitOverride = "none"
+reportIncompatibleVariableOverride = "none"
+reportUnknownVariableType = "none"
+reportUnknownMemberType = "none"
+reportUnknownArgumentType = "none"
+reportUnknownParameterType = "none"
+reportUnknownLambdaType = "none"
+reportMissingTypeArgument = "none"
+reportPrivateImportUsage = "none"
+reportUnusedCallResult = "none"
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+src = [".", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[dependency-groups]
+docs = [
+    # great-docs imports griffe's 2.x module layout; griffelib is the modern
+    # griffe (2.x) distribution, overriding the legacy griffe<2 pin great-docs
+    # itself still declares.
+    "griffelib>=2.0",
+    # Tracking great-docs main until a release newer than 0.13.0: main carries
+    # build-time GitHub widget stats (embedded via the CI GITHUB_TOKEN), which
+    # drop the navbar widget's client-side API calls — the source of GitHub 403
+    # errors on the published site.
+    # TODO(bootstrap): revert to a PyPI pin (`great-docs>=0.14`) once released.
+    "great-docs @ git+https://github.com/posit-dev/great-docs@main",
+]

spawnllm-0.1.0/spawnllm/__init__.py

@@ -0,0 +1,54 @@
+"""Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
+
+The top-level namespace exposes the CLI backends, subprocess transport, and
+structured-output helpers. The MLX engine lives under :mod:`spawnllm.mlx` and is
+imported lazily so that ``import spawnllm`` never pulls ``mlx_lm``/``zstandard``.
+"""
+
+from __future__ import annotations
+
+from spawnllm.backends import (
+    ClaudeCliBackend,
+    ClaudeNotAuthenticated,
+    ClaudeNotInstalled,
+    ClaudeReady,
+    ClaudeStatus,
+    CodexCliBackend,
+    LlmBackend,
+    LlmBackends,
+    check_status,
+)
+from spawnllm.call import call
+from spawnllm.proc import arun_cli, collect_process, map_concurrent, run_cli
+from spawnllm.structured import (
+    extract_structured,
+    parse_result_envelope,
+    parse_structured_output,
+    resolve_schema_path,
+    schema_for,
+)
+from spawnllm.types import TModel, TSpecialty
+
+__all__ = [
+    "ClaudeCliBackend",
+    "ClaudeNotAuthenticated",
+    "ClaudeNotInstalled",
+    "ClaudeReady",
+    "ClaudeStatus",
+    "CodexCliBackend",
+    "LlmBackend",
+    "LlmBackends",
+    "TModel",
+    "TSpecialty",
+    "arun_cli",
+    "call",
+    "check_status",
+    "collect_process",
+    "extract_structured",
+    "map_concurrent",
+    "parse_result_envelope",
+    "parse_structured_output",
+    "resolve_schema_path",
+    "run_cli",
+    "schema_for",
+]

spawnllm-0.1.0/spawnllm/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from spawnllm.cli import main
+
+if __name__ == "__main__":
+    main()

spawnllm-0.1.0/spawnllm/backends/__init__.py

@@ -0,0 +1,27 @@
+"""LLM CLI backends (Claude/Codex) and the specialty registry."""
+
+from __future__ import annotations
+
+from spawnllm.backends.base import LlmBackend
+from spawnllm.backends.claude import (
+    ClaudeCliBackend,
+    ClaudeNotAuthenticated,
+    ClaudeNotInstalled,
+    ClaudeReady,
+    ClaudeStatus,
+    check_status,
+)
+from spawnllm.backends.codex import CodexCliBackend
+from spawnllm.backends.registry import LlmBackends
+
+__all__ = [
+    "ClaudeCliBackend",
+    "ClaudeNotAuthenticated",
+    "ClaudeNotInstalled",
+    "ClaudeReady",
+    "ClaudeStatus",
+    "CodexCliBackend",
+    "LlmBackend",
+    "LlmBackends",
+    "check_status",
+]

spawnllm-0.1.0/spawnllm/backends/base.py

@@ -0,0 +1,53 @@
+"""Abstract interface for an LLM CLI backend."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, ClassVar
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from spawnllm.types import TModel
+
+
+class LlmBackend(ABC):
+    """Abstract interface for an LLM CLI backend.
+
+    Concrete backends map abstract model sizes to provider-specific model names
+    and encapsulate how to invoke the provider's CLI and parse the raw response.
+
+    Attributes:
+        models: Mapping from abstract model size to the provider's model name.
+    """
+
+    models: ClassVar[dict[TModel, str]]
+
+    @abstractmethod
+    def build_command(self, model: str, schema_path: str | None, agent: bool) -> list[str]:
+        """Build the CLI argv for a single invocation (prompt delivered via stdin).
+
+        Args:
+            model: Provider-specific model name.
+            schema_path: Schema argument for structured output, or ``None``.
+            agent: Whether the invocation may use tools / agent capabilities.
+
+        Returns:
+            The argv list to execute.
+        """
+
+    @abstractmethod
+    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
+        """Parse raw CLI stdout into text or a validated model.
+
+        Args:
+            raw: Raw stdout from the backend CLI.
+            response_model: Model to validate against, or ``None`` for raw text.
+
+        Returns:
+            ``raw`` when ``response_model`` is ``None``, else a validated instance.
+        """
+
+    @abstractmethod
+    def env(self) -> dict[str, str]:
+        """Return extra environment variables to set for the CLI invocation."""

spawnllm-0.1.0/spawnllm/backends/claude.py

@@ -0,0 +1,124 @@
+"""LlmBackend for the Anthropic ``claude`` CLI, plus install/auth status checks."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar
+
+from spawnllm.backends.base import LlmBackend
+from spawnllm.structured import parse_result_envelope, parse_structured_output
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from spawnllm.types import TModel
+
+CLAUDE_MODELS: dict[TModel, str] = {"small": "haiku", "medium": "sonnet", "large": "opus"}
+
+
+@dataclass(frozen=True)
+class ClaudeReady:
+    """The ``claude`` CLI is installed and authenticated."""
+
+
+@dataclass(frozen=True)
+class ClaudeNotInstalled:
+    """The ``claude`` CLI is not on PATH.
+
+    Attributes:
+        brew_available: Whether Homebrew is available to install it.
+    """
+
+    brew_available: bool
+
+
+@dataclass(frozen=True)
+class ClaudeNotAuthenticated:
+    """The ``claude`` CLI is installed but not authenticated."""
+
+
+ClaudeStatus = ClaudeReady | ClaudeNotInstalled | ClaudeNotAuthenticated
+
+
+def check_status(timeout: int = 10) -> ClaudeStatus:
+    """Return the install/auth status of the ``claude`` CLI."""
+    if not shutil.which("claude"):
+        return ClaudeNotInstalled(brew_available=bool(shutil.which("brew")))
+    result = subprocess.run(["claude", "auth", "status"], capture_output=True, text=True, timeout=timeout, check=False)
+    if result.returncode == 0:
+        return ClaudeReady()
+    return ClaudeNotAuthenticated()
+
+
+@dataclass(frozen=True)
+class ClaudeCliBackend(LlmBackend):
+    """:class:`LlmBackend` for the Anthropic ``claude`` CLI.
+
+    The default (no-arg) construction delivers the prompt over stdin with abstract
+    model tiers and structured-output parsing. The :meth:`cc_sentiment` preset
+    configures inline ``-p`` prompting with ``{is_error, result}`` envelope parsing.
+
+    Example:
+        >>> ClaudeCliBackend().build_command("haiku", None, agent=False)[0]
+        'claude'
+    """
+
+    models: ClassVar[dict[TModel, str]] = CLAUDE_MODELS
+
+    inline_system_prompt: str = ""
+    verbose: bool = False
+
+    @classmethod
+    def cc_sentiment(cls, *, system_prompt: str, verbose: bool = False) -> ClaudeCliBackend:
+        """Return a backend configured for inline ``-p`` prompting + envelope parsing."""
+        return cls(inline_system_prompt=system_prompt, verbose=verbose)
+
+    def build_command(self, model: str, schema_path: str | None, agent: bool) -> list[str]:
+        return [
+            "claude",
+            "-p",
+            "--no-session-persistence",
+            "--model",
+            model,
+            *(
+                ["--permission-mode", "auto", "--max-budget-usd", "1"]
+                if agent
+                else ["--system-prompt", "", "--setting-sources", "", "--strict-mcp-config"]
+            ),
+            *(["--json-schema", schema_path, "--output-format", "json"] if schema_path else []),
+        ]
+
+    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
+        return parse_structured_output(raw, response_model)
+
+    def env(self) -> dict[str, str]:
+        return {"CLAUDE_CODE_SIMPLE": "1"}
+
+    def build_argv(self, content: str, *, model: str) -> list[str]:
+        """Build the inline ``-p`` argv for the sentiment/pushback scoring path."""
+        argv = [
+            "claude",
+            "-p",
+            content,
+            "--model",
+            model,
+            "--system-prompt",
+            self.inline_system_prompt,
+            "--output-format",
+            "json",
+            "--max-turns",
+            "1",
+            "--tools",
+            "",
+            "--disable-slash-commands",
+        ]
+        if self.verbose:
+            argv.append("--verbose")
+        return argv
+
+    @staticmethod
+    def parse_result_envelope(stdout: bytes, *, argv: list[str], stderr: bytes) -> str:
+        """Parse the ``{is_error, result}`` JSON envelope; raise ``CalledProcessError`` on error."""
+        return parse_result_envelope(stdout, argv=argv, stderr=stderr)

spawnllm-0.1.0/spawnllm/backends/codex.py

@@ -0,0 +1,41 @@
+"""LlmBackend for the OpenAI ``codex`` CLI."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from spawnllm.backends.base import LlmBackend
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from spawnllm.types import TModel
+
+
+class CodexCliBackend(LlmBackend):
+    """:class:`LlmBackend` for the OpenAI ``codex`` CLI."""
+
+    models: ClassVar[dict[TModel, str]] = {
+        "small": "gpt-5.3-codex-spark",
+        "medium": "gpt-5.4-mini",
+        "large": "gpt-5.5",
+    }
+
+    def build_command(self, model: str, schema_path: str | None, agent: bool) -> list[str]:
+        return [
+            "codex",
+            "exec",
+            "--ephemeral",
+            "--sandbox",
+            "read-only",
+            "--model",
+            model,
+            *([] if agent else ["-c", "features.codex_hooks=false", "-c", "features.mcp_servers=false"]),
+            *(["--output-schema", schema_path] if schema_path else []),
+        ]
+
+    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
+        return raw if not response_model else response_model.model_validate_json(raw)
+
+    def env(self) -> dict[str, str]:
+        return {}

spawnllm-0.1.0/spawnllm/backends/registry.py

@@ -0,0 +1,27 @@
+"""Specialty → backend registry."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from spawnllm.backends.claude import ClaudeCliBackend
+from spawnllm.backends.codex import CodexCliBackend
+
+if TYPE_CHECKING:
+    from spawnllm.backends.base import LlmBackend
+    from spawnllm.types import TSpecialty
+
+
+class LlmBackends:
+    """Registry mapping each specialty to the :class:`LlmBackend` that serves it."""
+
+    LLM_BACKENDS: ClassVar[dict[TSpecialty, LlmBackend]] = {
+        "debugging": CodexCliBackend(),
+        "review": CodexCliBackend(),
+        "general": ClaudeCliBackend(),
+    }
+
+    @classmethod
+    def for_specialty(cls, specialty: TSpecialty) -> LlmBackend:
+        """Return the backend registered for ``specialty``."""
+        return cls.LLM_BACKENDS[specialty]

spawnllm-0.1.0/spawnllm/call.py

@@ -0,0 +1,42 @@
+"""High-level one-shot sync LLM call used by the debugging CLI."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from spawnllm.proc import run_cli
+from spawnllm.structured import resolve_schema_path, schema_for
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from spawnllm.backends.base import LlmBackend
+    from spawnllm.types import TModel
+
+
+def call(
+    prompt: str,
+    *,
+    backend: LlmBackend,
+    model: TModel = "small",
+    agent: bool = False,
+    response_model: type[BaseModel] | None = None,
+) -> str | BaseModel:
+    """Run one CLI-backed LLM call and parse its response.
+
+    Args:
+        prompt: The user prompt, delivered to the backend over stdin.
+        backend: The :class:`~spawnllm.backends.base.LlmBackend` to invoke.
+        model: Abstract model tier (``small``/``medium``/``large``).
+        agent: Whether the call may use tools / agent capabilities.
+        response_model: Pydantic model for structured output, or ``None`` for text.
+
+    Returns:
+        The raw text response, or a validated ``response_model`` instance.
+    """
+    schema = schema_for(response_model) if response_model is not None else None
+    schema_path = resolve_schema_path(backend, schema)
+    cmd = backend.build_command(backend.models[model], schema_path, agent)
+    raw = run_cli(cmd, input=prompt, env=os.environ | backend.env())
+    return backend.parse_response(raw, response_model)

spawnllm-0.1.0/spawnllm/cli.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import sys
+from typing import cast
+
+import click
+from loguru import logger
+
+from spawnllm.backends import ClaudeCliBackend, CodexCliBackend
+from spawnllm.call import call as call_backend
+from spawnllm.types import TModel
+
+BACKENDS = ("claude", "codex", "mlx")
+CLI_BACKENDS = {"claude": ClaudeCliBackend, "codex": CodexCliBackend}
+
+
+@click.group()
+@click.version_option(package_name="spawnllm")
+def main() -> None:
+    """Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools."""
+
+
+@main.command()
+def backends() -> None:
+    """List the LLM backends spawnllm can drive."""
+    logger.debug("backends invoked")
+    for name in BACKENDS:
+        click.echo(name)
+
+
+@main.command()
+@click.option("--backend", type=click.Choice(["claude", "codex"]), required=True)
+@click.option("--model", type=click.Choice(["small", "medium", "large"]), default="small")
+@click.option("--agent", is_flag=True, help="Allow tools / agent capabilities.")
+@click.argument("prompt", required=False)
+def call(backend: str, model: str, agent: bool, prompt: str | None) -> None:
+    """Make a one-off LLM call (reads PROMPT or stdin) and print the response."""
+    text = prompt if prompt is not None else sys.stdin.read()
+    result = call_backend(text, backend=CLI_BACKENDS[backend](), model=cast(TModel, model), agent=agent)
+    click.echo(result)

spawnllm-0.1.0/spawnllm/mlx/__init__.py

@@ -0,0 +1,38 @@
+"""Local MLX engine, adapter codec, fuser, and runtime patches.
+
+Imports here are lazy so that ``import spawnllm`` never pulls ``mlx_lm``/``zstandard``;
+only consumers that touch ``spawnllm.mlx`` attributes load the heavy dependencies.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from spawnllm.mlx.codec import AdapterCodec
+    from spawnllm.mlx.engine import MlxEngine
+    from spawnllm.mlx.fuse import AdapterFuser
+    from spawnllm.mlx.patches import MLXPatches
+
+__all__ = ["AdapterCodec", "AdapterFuser", "MLXPatches", "MlxEngine"]
+
+
+def __getattr__(name: str) -> object:
+    match name:
+        case "AdapterCodec":
+            from spawnllm.mlx.codec import AdapterCodec
+
+            return AdapterCodec
+        case "AdapterFuser":
+            from spawnllm.mlx.fuse import AdapterFuser
+
+            return AdapterFuser
+        case "MlxEngine":
+            from spawnllm.mlx.engine import MlxEngine
+
+            return MlxEngine
+        case "MLXPatches":
+            from spawnllm.mlx.patches import MLXPatches
+
+            return MLXPatches
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

spawnllm-0.1.0/spawnllm/mlx/codec.py

@@ -0,0 +1,92 @@
+"""Cross-platform LoRA adapter codec (byte-shuffle + zstd; imports without ``mlx_lm``)."""
+
+from __future__ import annotations
+
+import hashlib
+import struct
+from pathlib import Path
+from typing import ClassVar
+
+import orjson
+
+
+class AdapterCodec:
+    """Compress/decompress a homogeneous-dtype safetensors adapter with byte-shuffle + zstd.
+
+    Subclasses override :attr:`DIR`/:attr:`ZST`/:attr:`CONFIG` to point at their
+    shipped package data.
+
+    Example:
+        >>> AdapterCodec.encode(Path("adapters.safetensors"))
+        >>> AdapterCodec.digest()
+    """
+
+    DIR: ClassVar[Path] = Path(__file__).parent
+    ZST: ClassVar[Path] = DIR / "adapters.safetensors.zst"
+    CONFIG: ClassVar[Path] = DIR / "adapter_config.json"
+    TYPESIZES: ClassVar[dict[str, int]] = {"F32": 4, "BF16": 2, "F16": 2}
+    COMPRESSION_LEVEL: ClassVar[int] = 19
+
+    @classmethod
+    def digest(cls) -> str:
+        return hashlib.sha256(cls.ZST.read_bytes()).hexdigest()[:16]
+
+    @classmethod
+    def encode(cls, src: Path) -> None:
+        import zstandard as zstd
+
+        raw = src.read_bytes()
+        cls._assert_homogeneous_dtype(raw)
+        cls.ZST.write_bytes(zstd.ZstdCompressor(level=cls.COMPRESSION_LEVEL).compress(cls._walk(raw, shuffle=True)))
+
+    @classmethod
+    def decode(cls, dst: Path) -> None:
+        import zstandard as zstd
+
+        dst.write_bytes(cls._walk(zstd.ZstdDecompressor().decompress(cls.ZST.read_bytes()), shuffle=False))
+
+    @classmethod
+    def dtype(cls) -> str:
+        import zstandard as zstd
+
+        raw = zstd.ZstdDecompressor().decompress(cls.ZST.read_bytes())
+        cls._assert_homogeneous_dtype(raw)
+        header_end = 8 + struct.unpack("<Q", raw[:8])[0]
+        return next(v["dtype"] for k, v in orjson.loads(raw[8:header_end]).items() if k != "__metadata__")
+
+    @classmethod
+    def _walk(cls, raw: bytes, *, shuffle: bool) -> bytes:
+        header_end = 8 + struct.unpack("<Q", raw[:8])[0]
+        body = raw[header_end:]
+        out = bytearray(raw[:header_end])
+        cursor = 0
+        for name, meta in sorted(
+            ((k, v) for k, v in orjson.loads(raw[8:header_end]).items() if k != "__metadata__"),
+            key=lambda kv: kv[1]["data_offsets"][0],
+        ):
+            assert meta["dtype"] in cls.TYPESIZES, f"{name}: unsupported dtype {meta['dtype']}"
+            typesize = cls.TYPESIZES[meta["dtype"]]
+            nbytes = meta["data_offsets"][1] - meta["data_offsets"][0]
+            chunk = body[cursor : cursor + nbytes]
+            out.extend(cls._shuffle(chunk, typesize) if shuffle else cls._unshuffle(chunk, typesize))
+            cursor += nbytes
+        return bytes(out)
+
+    @classmethod
+    def _assert_homogeneous_dtype(cls, raw: bytes) -> None:
+        header_end = 8 + struct.unpack("<Q", raw[:8])[0]
+        dtypes = {v["dtype"] for k, v in orjson.loads(raw[8:header_end]).items() if k != "__metadata__"}
+        assert len(dtypes) == 1, f"adapter must be homogeneous-dtype, got {dtypes}"
+        assert dtypes.issubset(cls.TYPESIZES.keys()), f"unsupported dtype: {dtypes}"
+
+    @classmethod
+    def _shuffle(cls, chunk: bytes, typesize: int) -> bytes:
+        import numpy as np
+
+        return np.frombuffer(chunk, dtype=np.uint8).reshape(-1, typesize).T.tobytes()
+
+    @classmethod
+    def _unshuffle(cls, chunk: bytes, typesize: int) -> bytes:
+        import numpy as np
+
+        return np.frombuffer(chunk, dtype=np.uint8).reshape(typesize, -1).T.tobytes()

spawnllm-0.1.0/spawnllm/mlx/engine.py

@@ -0,0 +1,148 @@
+"""Domain-agnostic MLX batch-inference engine running on a dedicated worker thread."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import platform
+import queue
+import sys
+import threading
+from typing import TYPE_CHECKING, Any
+
+import anyio.to_thread
+
+from spawnllm.mlx.patches import MLXPatches
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+WORKER_STOP = object()
+
+
+class MlxEngine:
+    """Run batched MLX inference on a dedicated worker thread.
+
+    Sentiment/domain specifics are injected: ``logits_processor_factory`` builds the
+    per-model logit processor from the loaded tokenizer, and ``prefix_messages`` is
+    the cached system/demo prefix shared across a batch.
+    """
+
+    def __init__(
+        self,
+        fused_dir: Path,
+        *,
+        logits_processor_factory: Callable[[Any], Callable[..., Any]],
+        prefix_messages: list[dict[str, str]],
+        batch_size: int,
+        worker_name: str = "mlx",
+    ) -> None:
+        if sys.platform != "darwin" or platform.machine() != "arm64":
+            raise RuntimeError("The MLX engine requires macOS on Apple Silicon. Use a CLI backend on this platform.")
+        self._fused_dir = fused_dir
+        self._logits_processor_factory = logits_processor_factory
+        self._prefix_messages = prefix_messages
+        self._batch_size = batch_size
+        self._inbox: queue.SimpleQueue = queue.SimpleQueue()
+        self._loaded = threading.Event()
+        self._init_error: BaseException | None = None
+        self._thread = threading.Thread(target=self._worker, daemon=True, name=worker_name)
+        self._thread.start()
+
+    def _worker(self) -> None:
+        try:
+            self._load()
+        except BaseException as exc:
+            self._init_error = exc
+            self._loaded.set()
+            return
+        self._loaded.set()
+        while True:
+            job = self._inbox.get()
+            if job is WORKER_STOP:
+                return
+            fn, args, on_result, on_error = job
+            try:
+                on_result(fn(*args))
+            except BaseException as exc:
+                on_error(exc)
+
+    def _load(self) -> None:
+        from mlx_lm import batch_generate, load
+
+        MLXPatches.apply()
+        self.model, self.tokenizer = load(str(self._fused_dir))
+        self.logit_processor = self._logits_processor_factory(self.tokenizer)
+        self.prefix_messages = self._prefix_messages
+        self.prefix_tokens = self.tokenizer.apply_chat_template(
+            self.prefix_messages, tokenize=True, add_generation_prompt=False
+        )
+        self.base_cache = batch_generate(
+            self.model,
+            self.tokenizer,
+            [self.prefix_tokens],
+            max_tokens=1,
+            logits_processors=[self.logit_processor],
+            return_prompt_caches=True,
+        ).caches[0]
+
+    async def ensure_loaded(self) -> None:
+        await anyio.to_thread.run_sync(self._loaded.wait)
+        if self._init_error is not None:
+            raise self._init_error
+
+    async def submit[R](self, fn: Callable[..., R], *args: Any) -> R:
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future = loop.create_future()
+        self._inbox.put(
+            (
+                fn,
+                args,
+                lambda value: loop.call_soon_threadsafe(fut.set_result, value),
+                lambda exc: loop.call_soon_threadsafe(fut.set_exception, exc),
+            )
+        )
+        return await fut
+
+    def _generate_chunk(self, chunk: list[list[dict[str, str]]]) -> list[str]:
+        from mlx_lm import batch_generate
+
+        suffixes = [
+            self.tokenizer.apply_chat_template(messages, tokenize=True, add_generation_prompt=True)[
+                len(self.prefix_tokens) :
+            ]
+            for messages in chunk
+        ]
+        return batch_generate(
+            self.model,
+            self.tokenizer,
+            suffixes,
+            max_tokens=1,
+            logits_processors=[self.logit_processor],
+            prompt_caches=[copy.deepcopy(self.base_cache) for _ in suffixes],
+        ).texts
+
+    async def generate(
+        self,
+        message_lists: list[list[dict[str, str]]],
+        on_progress: Callable[[int], None],
+    ) -> list[str]:
+        order = sorted(range(len(message_lists)), key=lambda i: len(message_lists[i][-1]["content"]))
+        responses: list[str] = [""] * len(message_lists)
+        for start in range(0, len(order), self._batch_size):
+            slice_ = order[start : start + self._batch_size]
+            chunk = [message_lists[i] for i in slice_]
+            chunk_responses = await self.submit(self._generate_chunk, chunk)
+            for i, r in zip(slice_, chunk_responses, strict=True):
+                responses[i] = r
+            on_progress(len(chunk))
+        return responses
+
+    def peak_memory_gb(self) -> float:
+        import resource
+
+        return resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / (1024**3)
+
+    async def close(self) -> None:
+        self._inbox.put(WORKER_STOP)

spawnllm-0.1.0/spawnllm/mlx/fuse.py

@@ -0,0 +1,52 @@
+"""Fuse a shipped LoRA adapter into a base MLX model, cached in the HF-hub layout."""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from spawnllm.mlx.codec import AdapterCodec
+
+
+class AdapterFuser:
+    @classmethod
+    def ensure_fused(
+        cls,
+        model_repo: str,
+        *,
+        codec: AdapterCodec,
+        cache_namespace: str,
+        tqdm_class: type | None = None,
+    ) -> Path:
+        from huggingface_hub.constants import HF_HUB_CACHE
+
+        digest = codec.digest()
+        repo_dir = Path(HF_HUB_CACHE) / f"models--{cache_namespace}-{digest}"
+        fused_dir = repo_dir / "snapshots" / digest
+        if (fused_dir / "config.json").exists():
+            return fused_dir
+
+        from huggingface_hub import snapshot_download
+        from mlx.utils import tree_unflatten
+        from mlx_lm.utils import load_adapters, load_model, load_tokenizer, save
+
+        src_path = Path(snapshot_download(model_repo, tqdm_class=tqdm_class))
+        with tempfile.TemporaryDirectory() as tmp:
+            staging = Path(tmp)
+            (staging / "adapter_config.json").write_bytes(codec.CONFIG.read_bytes())
+            codec.decode(staging / "adapters.safetensors")
+            model, config = load_model(src_path, lazy=False, strict=False)
+            model = load_adapters(model, str(staging))
+            model.eval()
+            tokenizer = load_tokenizer(src_path, eos_token_ids=config.get("eos_token_id"))
+            model.update_modules(
+                tree_unflatten([(n, m.fuse()) for n, m in model.named_modules() if hasattr(m, "fuse")])
+            )
+            fused_dir.mkdir(parents=True, exist_ok=True)
+            save(fused_dir, src_path, model, tokenizer, config, donate_model=True)
+
+        (refs := repo_dir / "refs").mkdir(parents=True, exist_ok=True)
+        (refs / "main").write_text(digest)
+        return fused_dir

spawnllm-0.1.0/spawnllm/mlx/patches.py

@@ -0,0 +1,43 @@
+"""Runtime patches applied in-worker before the first ``batch_generate``."""
+
+from __future__ import annotations
+
+import contextlib
+import time
+
+
+class MLXPatches:
+    applied: bool = False
+
+    @classmethod
+    def apply(cls) -> None:
+        if cls.applied:
+            return
+        cls.applied = True
+        cls._apply_batchstats_zerodiv_guard()
+
+    @staticmethod
+    def _apply_batchstats_zerodiv_guard() -> None:
+        import mlx.core as mx
+        from mlx_lm.generate import BatchGenerator, BatchStats
+
+        @contextlib.contextmanager
+        def stats(self, stats: BatchStats | None = None):
+            stats = stats or BatchStats()
+            self._prompt_tokens_counter = 0
+            self._prompt_time_counter = 0
+            self._gen_tokens_counter = 0
+            tic = time.perf_counter()
+            try:
+                yield stats
+            finally:
+                total_time = time.perf_counter() - tic
+                stats.prompt_tokens += self._prompt_tokens_counter
+                stats.prompt_time += self._prompt_time_counter
+                stats.prompt_tps = stats.prompt_tokens / max(stats.prompt_time, 1e-9)
+                stats.generation_tokens += self._gen_tokens_counter
+                stats.generation_time += total_time - self._prompt_time_counter
+                stats.generation_tps = stats.generation_tokens / max(stats.generation_time, 1e-9)
+                stats.peak_memory = max(stats.peak_memory, mx.get_peak_memory() / 1e9)
+
+        BatchGenerator.stats = stats

spawnllm-0.1.0/spawnllm/proc.py

@@ -0,0 +1,108 @@
+"""Subprocess transport for CLI-backed LLM calls (sync ``run_cli`` + async ``arun_cli``)."""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+from collections.abc import Awaitable, Callable, Sequence
+
+__all__ = ["arun_cli", "collect_process", "map_concurrent", "run_cli"]
+
+
+def run_cli(
+    argv: list[str],
+    *,
+    input: str | None = None,
+    timeout: int = 30,
+    env: dict[str, str] | None = None,
+    cwd: str | None = None,
+) -> str:
+    result = subprocess.run(
+        argv,
+        input=input,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        env=env,
+        cwd=cwd,
+    )
+    if result.returncode != 0:
+        err = subprocess.CalledProcessError(result.returncode, argv, output=result.stdout, stderr=result.stderr)
+        err.add_note(f"argv: {argv}")
+        err.add_note(f"exit_code: {result.returncode}")
+        err.add_note(f"stderr: {result.stderr[-4096:]}")
+        err.add_note(f"stdout: {result.stdout[-4096:]}")
+        raise err
+    return result.stdout
+
+
+async def collect_process(
+    proc: asyncio.subprocess.Process,
+    *,
+    stderr_tee: Callable[[bytes], None] | None = None,
+) -> tuple[bytes, bytes, int]:
+    assert proc.stderr is not None, "create_subprocess_exec was called with stderr=PIPE"
+    assert proc.stdout is not None, "create_subprocess_exec was called with stdout=PIPE"
+    stderr_buf = bytearray()
+    async with asyncio.TaskGroup() as tg:
+        tg.create_task(_tee_stderr(proc.stderr, stderr_buf, stderr_tee))
+        stdout_task = tg.create_task(proc.stdout.read())
+        rc_task = tg.create_task(proc.wait())
+    return stdout_task.result(), bytes(stderr_buf), rc_task.result()
+
+
+async def _tee_stderr(
+    stream: asyncio.StreamReader,
+    buf: bytearray,
+    stderr_tee: Callable[[bytes], None] | None,
+) -> None:
+    async for raw in stream:
+        buf.extend(raw)
+        if stderr_tee is not None:
+            stderr_tee(raw)
+
+
+async def arun_cli(
+    argv: list[str],
+    *,
+    input: str | None = None,
+    env: dict[str, str] | None = None,
+    cwd: str | None = None,
+    stderr_tee: Callable[[bytes], None] | None = None,
+) -> bytes:
+    proc = await asyncio.create_subprocess_exec(
+        *argv,
+        stdin=asyncio.subprocess.PIPE if input is not None else None,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        env=env,
+        cwd=cwd,
+    )
+    if input is not None:
+        assert proc.stdin is not None, "create_subprocess_exec was called with stdin=PIPE"
+        proc.stdin.write(input.encode())
+        await proc.stdin.drain()
+        proc.stdin.close()
+    stdout, stderr, rc = await collect_process(proc, stderr_tee=stderr_tee)
+    if rc != 0:
+        raise subprocess.CalledProcessError(rc, argv, output=stdout, stderr=stderr)
+    return stdout
+
+
+async def map_concurrent[T, R](
+    items: Sequence[T],
+    fn: Callable[[T], Awaitable[R]],
+    *,
+    limit: int,
+    on_done: Callable[[int], None] | None = None,
+) -> list[R]:
+    sem = asyncio.Semaphore(limit)
+
+    async def one(item: T) -> R:
+        async with sem:
+            result = await fn(item)
+        if on_done is not None:
+            on_done(1)
+        return result
+
+    return list(await asyncio.gather(*(one(item) for item in items)))

spawnllm-0.1.0/spawnllm/structured.py

@@ -0,0 +1,65 @@
+"""Structured-output helpers: JSON-schema build, schema-path resolution, response parsing."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+from typing import TYPE_CHECKING, Any, cast
+
+from spawnllm.backends.codex import CodexCliBackend
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from spawnllm.backends.base import LlmBackend
+
+__all__ = [
+    "extract_structured",
+    "parse_result_envelope",
+    "parse_structured_output",
+    "resolve_schema_path",
+    "schema_for",
+]
+
+
+def schema_for(model: type[BaseModel]) -> str:
+    return json.dumps(model.model_json_schema() | {"additionalProperties": False})
+
+
+def resolve_schema_path(backend: LlmBackend, schema: str | None) -> str | None:
+    if not schema:
+        return None
+    if isinstance(backend, CodexCliBackend):
+        fd, path = tempfile.mkstemp(suffix=".json")
+        os.write(fd, schema.encode())
+        os.close(fd)
+        return path
+    return schema
+
+
+def extract_structured(events: list[dict[str, Any]], model: type[BaseModel]) -> BaseModel | None:
+    """Return the validated ``structured_output`` from a stream-json event list, if present."""
+    for e in events:
+        if e.get("type") == "result" and "structured_output" in e:
+            return model.model_validate(e["structured_output"])
+    return None
+
+
+def parse_structured_output(raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
+    if not response_model:
+        return raw
+    data = json.loads(raw)
+    if isinstance(data, list) and data:
+        return extract_structured(
+            cast(list[dict[str, Any]], data), response_model
+        ) or response_model.model_validate_json(raw)
+    return response_model.model_validate_json(raw)
+
+
+def parse_result_envelope(stdout: bytes, *, argv: list[str], stderr: bytes) -> str:
+    data = json.loads(stdout)
+    if data["is_error"]:
+        raise subprocess.CalledProcessError(0, argv, output=stdout, stderr=stderr)
+    return data["result"]

spawnllm-0.1.0/spawnllm/types.py

@@ -0,0 +1,10 @@
+"""Shared type aliases for the LLM-calling surface."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+__all__ = ["TModel", "TSpecialty"]
+
+TSpecialty = Literal["debugging", "review", "general"]
+TModel = Literal["small", "medium", "large"]