subagent-fleet 0.0.1__py3-none-any.whl

subagent_fleet/__init__.py

@@ -0,0 +1,3 @@
+"""subagent-fleet package."""
+
+__version__ = "0.0.1"

subagent_fleet/cli.py

@@ -0,0 +1,331 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from subagent_fleet.config import ConfigError, FleetConfig, config_to_plain_dict, load_config
+from subagent_fleet.defaults import STARTER_FLEET_YAML
+from subagent_fleet.discovery import discovery_to_json, discover_fleet
+from subagent_fleet.generators import generate_claude_agents, generate_env_file, generate_litellm_config
+from subagent_fleet.plugins import PluginInstallError, install_plugin_marketplaces
+from subagent_fleet.skills import (
+    ASSISTANT_TARGETS,
+    BUNDLED_SKILLS,
+    SkillInstallError,
+    install_skills,
+)
+from subagent_fleet.status import get_status, routes_to_json
+from subagent_fleet.warmup import warmup_models
+
+app = typer.Typer(help="Run Claude Code-style subagents across your local model fleet.", no_args_is_help=True)
+skills_app = typer.Typer(help="Install assistant skills for using subagent-fleet.", no_args_is_help=True)
+plugins_app = typer.Typer(help="Install assistant plugin marketplace bundles.", no_args_is_help=True)
+app.add_typer(skills_app, name="skills")
+app.add_typer(plugins_app, name="plugins")
+console = Console()
+
+
+def _load_or_exit(path: Path) -> FleetConfig:
+    try:
+        return load_config(path)
+    except ConfigError as exc:
+        console.print(f"[red]Invalid {path}:[/red]\n\n{exc}")
+        raise typer.Exit(1) from exc
+
+
+@app.command()
+def init(
+    output: Annotated[Path, typer.Option("--output", help="Path to write the starter fleet config.")] = Path("fleet.yaml"),
+    force: Annotated[bool, typer.Option("--force", help="Overwrite an existing config file.")] = False,
+) -> None:
+    """Create a starter fleet.yaml."""
+    if output.exists() and not force:
+        console.print(f"[red]{output} already exists. Use --force to overwrite.[/red]")
+        raise typer.Exit(1)
+    output.write_text(STARTER_FLEET_YAML)
+    console.print(f"Created {output}")
+    console.print("\nEdit it with your Ollama node endpoints, then run:\n")
+    console.print("  subagent-fleet discover")
+    console.print("  subagent-fleet generate")
+
+
+@app.command()
+def validate(config: Annotated[Path, typer.Option("--config", help="Path to fleet.yaml.")] = Path("fleet.yaml")) -> None:
+    """Validate fleet.yaml."""
+    fleet = _load_or_exit(config)
+    console.print(f"{config} is valid.")
+    for warning in fleet.alias_warnings():
+        console.print(f"[yellow]Warning:[/yellow] {warning}")
+
+
+@app.command()
+def discover(
+    config: Annotated[Path, typer.Option("--config", help="Path to fleet.yaml.")] = Path("fleet.yaml"),
+    as_json: Annotated[bool, typer.Option("--json", help="Print machine-readable JSON.")] = False,
+    write: Annotated[bool, typer.Option("--write", help="Write .subagent-fleet/discovery.json.")] = False,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Show connection errors for offline nodes.")] = False,
+) -> None:
+    """Discover models available on configured Ollama nodes."""
+    fleet = _load_or_exit(config)
+    results = discover_fleet(fleet)
+    payload = {"fleet": fleet.project.name, "nodes": discovery_to_json(results)}
+
+    if write:
+        discovery_path = Path(".subagent-fleet/discovery.json")
+        discovery_path.parent.mkdir(parents=True, exist_ok=True)
+        discovery_path.write_text(json.dumps(payload, indent=2) + "\n")
+
+    if as_json:
+        console.print(json.dumps(payload, indent=2))
+        return
+
+    console.print(f"Fleet: {fleet.project.name}\n")
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Node")
+    table.add_column("Status")
+    table.add_column("Models")
+    if verbose:
+        table.add_column("Error")
+    for result in results:
+        status = "[green]online[/green]" if result.online else "[red]offline[/red]"
+        row = [result.name, status, ", ".join(result.models) if result.models else "-"]
+        if verbose:
+            row.append(result.error or "")
+        table.add_row(*row)
+    console.print(table)
+    if write:
+        console.print(f"\nWrote {discovery_path}")
+
+
+@app.command()
+def generate(
+    config: Annotated[Path, typer.Option("--config", help="Path to fleet.yaml.")] = Path("fleet.yaml"),
+    out: Annotated[Path, typer.Option("--out", help="Output root.")] = Path("."),
+    litellm_only: Annotated[bool, typer.Option("--litellm-only", help="Only generate LiteLLM config.")] = False,
+    claude_only: Annotated[bool, typer.Option("--claude-only", help="Only generate Claude agent files.")] = False,
+    force: Annotated[bool, typer.Option("--force", help="Overwrite generated files.")] = False,
+) -> None:
+    """Generate LiteLLM, Claude Code agent, and environment files."""
+    if litellm_only and claude_only:
+        console.print("[red]Use at most one of --litellm-only or --claude-only.[/red]")
+        raise typer.Exit(1)
+
+    fleet = _load_or_exit(config)
+    source = str(config)
+    generated: list[Path] = []
+    try:
+        if not claude_only:
+            generated.append(generate_litellm_config(fleet, out / "litellm_config.yaml", source=source, force=force))
+        if not litellm_only:
+            generated.extend(generate_claude_agents(fleet, out / ".claude" / "agents", source=source, force=force))
+            if not claude_only:
+                generated.append(generate_env_file(fleet, out / ".env.subagent-fleet", source=source, force=force))
+    except FileExistsError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+
+    console.print("Generated:")
+    for path in generated:
+        console.print(f"  {path}")
+    if not claude_only:
+        console.print("\nStart LiteLLM with:")
+        console.print(f"  litellm --config {out / 'litellm_config.yaml'} --host {fleet.project.gateway.host} --port {fleet.project.gateway.port}")
+    if not litellm_only and not claude_only:
+        console.print("\nThen run:")
+        console.print("  source .env.subagent-fleet")
+        console.print("  claude")
+    for warning in fleet.alias_warnings():
+        console.print(f"[yellow]Warning:[/yellow] {warning}")
+
+
+@app.command()
+def warmup(
+    config: Annotated[Path, typer.Option("--config", help="Path to fleet.yaml.")] = Path("fleet.yaml"),
+    model: Annotated[str | None, typer.Option("--model", help="Only warm this configured model name.")] = None,
+    agent: Annotated[str | None, typer.Option("--agent", help="Only warm the model used by this agent.")] = None,
+) -> None:
+    """Preload configured Ollama models."""
+    fleet = _load_or_exit(config)
+    try:
+        results = warmup_models(fleet, model_name=model, agent_name=agent)
+    except ValueError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+
+    console.print("Warming models:\n")
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Model")
+    table.add_column("Node")
+    table.add_column("Ollama Model")
+    table.add_column("Status")
+    for result in results:
+        table.add_row(
+            result.model_name,
+            result.node_name,
+            result.ollama_model,
+            "[green]ok[/green]" if result.ok else f"[red]failed[/red] {result.error}",
+        )
+    console.print(table)
+    if any(not result.ok for result in results):
+        raise typer.Exit(1)
+
+
+@app.command()
+def status(
+    config: Annotated[Path, typer.Option("--config", help="Path to fleet.yaml.")] = Path("fleet.yaml"),
+    as_json: Annotated[bool, typer.Option("--json", help="Print machine-readable JSON.")] = False,
+) -> None:
+    """Show node status and agent routing."""
+    fleet = _load_or_exit(config)
+    nodes, routes = get_status(fleet)
+    if as_json:
+        console.print(
+            json.dumps(
+                {
+                    "fleet": fleet.project.name,
+                    "nodes": discovery_to_json(nodes),
+                    "routes": routes_to_json(routes),
+                },
+                indent=2,
+            )
+        )
+        return
+
+    console.print(f"Fleet: {fleet.project.name}\n")
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Node")
+    table.add_column("Status")
+    table.add_column("Endpoint")
+    table.add_column("Models")
+    for node in nodes:
+        table.add_row(
+            node.name,
+            "[green]online[/green]" if node.online else "[red]offline[/red]",
+            node.endpoint,
+            ", ".join(node.models) if node.models else "-",
+        )
+    console.print(table)
+    _print_routes(routes)
+
+
+@app.command()
+def doctor(config: Annotated[Path, typer.Option("--config", help="Path to fleet.yaml.")] = Path("fleet.yaml")) -> None:
+    """Validate config and print local-network security guidance."""
+    fleet = _load_or_exit(config)
+    console.print(f"{config} is valid.")
+    console.print("\nSecurity checks:")
+    console.print("- Do not expose Ollama directly to the public internet.")
+    console.print("- Do not expose LiteLLM without authentication.")
+    console.print("- Prefer LAN, firewall rules, Tailscale, or WireGuard.")
+    console.print(f"- Use a non-default {fleet.project.gateway.master_key_env} beyond local dev.")
+    console.print("\nOllama worker setup hint:")
+    console.print('  launchctl setenv OLLAMA_HOST "0.0.0.0:11434"')
+    console.print('  launchctl setenv OLLAMA_KEEP_ALIVE "-1"')
+    console.print('  launchctl setenv OLLAMA_NUM_PARALLEL "1"')
+    console.print('  launchctl setenv OLLAMA_MAX_LOADED_MODELS "1"')
+
+
+@app.command()
+def clean(out: Annotated[Path, typer.Option("--out", help="Output root to clean.")] = Path("."), force: bool = False) -> None:
+    """Remove generated files from an output root."""
+    targets = [out / "litellm_config.yaml", out / ".env.subagent-fleet"]
+    targets.extend((out / ".claude" / "agents").glob("*.md") if (out / ".claude" / "agents").exists() else [])
+    if not force:
+        console.print("Files that would be removed:")
+        for target in targets:
+            console.print(f"  {target}")
+        console.print("\nRun with --force to remove them.")
+        return
+    for target in targets:
+        target.unlink(missing_ok=True)
+    console.print("Removed generated files.")
+
+
+@skills_app.command("list")
+def list_skills() -> None:
+    """List bundled skills and supported assistant targets."""
+    skill_table = Table(title="Bundled skills", show_header=True, header_style="bold")
+    skill_table.add_column("Skill")
+    skill_table.add_column("Description")
+    for skill in BUNDLED_SKILLS.values():
+        skill_table.add_row(skill.name, skill.description)
+    console.print(skill_table)
+
+    target_table = Table(title="Targets", show_header=True, header_style="bold")
+    target_table.add_column("Target")
+    target_table.add_column("Install Directory")
+    target_table.add_column("Description")
+    for target in ASSISTANT_TARGETS.values():
+        target_table.add_row(target.name, str(target.directory), target.description)
+    console.print(target_table)
+
+
+@skills_app.command("install")
+def install_assistant_skills(
+    out: Annotated[Path, typer.Option("--out", help="Project root or output directory.")] = Path("."),
+    target: Annotated[
+        list[str] | None,
+        typer.Option("--target", "-t", help="Assistant target: all, claude-code, codex, opencode. Can be repeated or comma-separated."),
+    ] = None,
+    skill: Annotated[
+        list[str] | None,
+        typer.Option("--skill", "-s", help="Bundled skill: all, subagent-fleet-setup, subagent-fleet-operations. Can be repeated or comma-separated."),
+    ] = None,
+    force: Annotated[bool, typer.Option("--force", help="Overwrite existing installed skill files.")] = False,
+) -> None:
+    """Install bundled assistant skills for Claude Code, Codex, OpenCode, or all targets."""
+    try:
+        results = install_skills(output_root=out, targets=target or ["all"], skills=skill or ["all"], force=force)
+    except (FileExistsError, SkillInstallError) as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+
+    console.print("Installed skills:")
+    for result in results:
+        console.print(f"  {result.target}: {result.skill} -> {result.path}")
+
+
+@plugins_app.command("install")
+def install_assistant_plugins(
+    out: Annotated[Path, typer.Option("--out", help="Marketplace root or output directory.")] = Path("."),
+    target: Annotated[
+        list[str] | None,
+        typer.Option("--target", "-t", help="Plugin target: all, claude-code, codex. Can be repeated or comma-separated."),
+    ] = None,
+    force: Annotated[bool, typer.Option("--force", help="Overwrite existing plugin marketplace files.")] = False,
+) -> None:
+    """Install Claude Code and Codex plugin marketplace bundles."""
+    try:
+        results = install_plugin_marketplaces(output_root=out, targets=target or ["all"], force=force)
+    except (FileExistsError, PluginInstallError) as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+
+    console.print("Installed plugin marketplace files:")
+    for result in results:
+        console.print(f"  {result.target}: {result.path}")
+    console.print("\nPlugin skills included:")
+    console.print("  subagent-fleet-bootstrap")
+    console.print("  subagent-fleet-setup")
+    console.print("  subagent-fleet-operations")
+
+
+def _print_routes(routes: list[object]) -> None:
+    console.print("\nAgent routing:\n")
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Agent")
+    table.add_column("Node")
+    table.add_column("Ollama Model")
+    table.add_column("LiteLLM Alias")
+    for route in routes:
+        table.add_row(route.agent, route.node, route.ollama_model, route.litellm_alias)
+    console.print(table)
+
+
+if __name__ == "__main__":
+    app()

subagent_fleet/config.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import AnyHttpUrl, BaseModel, ConfigDict, Field, ValidationError, field_validator, model_validator
+
+AGENT_NAME_RE = re.compile(r"^[a-z0-9_-]+$")
+DEFAULT_AGENT_PROMPT = "You are a local subagent. Follow the agent description and return a concise, useful response."
+
+
+class ConfigError(ValueError):
+    """Raised when fleet.yaml cannot be loaded or validated."""
+
+
+class UniqueKeyLoader(yaml.SafeLoader):
+    """YAML loader that rejects duplicate mapping keys."""
+
+
+def _construct_mapping(loader: UniqueKeyLoader, node: yaml.MappingNode, deep: bool = False) -> dict[Any, Any]:
+    mapping: dict[Any, Any] = {}
+    for key_node, value_node in node.value:
+        key = loader.construct_object(key_node, deep=deep)
+        if key in mapping:
+            raise yaml.constructor.ConstructorError(
+                "while constructing a mapping",
+                node.start_mark,
+                f"found duplicate key: {key}",
+                key_node.start_mark,
+            )
+        mapping[key] = loader.construct_object(value_node, deep=deep)
+    return mapping
+
+
+UniqueKeyLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _construct_mapping)
+
+
+class GatewayConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    provider: str = "litellm"
+    host: str = "127.0.0.1"
+    port: int = Field(default=4000, ge=1, le=65535)
+    master_key_env: str = "LITELLM_MASTER_KEY"
+
+
+class ProjectConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    gateway: GatewayConfig = Field(default_factory=GatewayConfig)
+
+
+class NodeConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    endpoint: AnyHttpUrl
+    tags: list[str] = Field(default_factory=list)
+
+    @property
+    def endpoint_str(self) -> str:
+        return str(self.endpoint).rstrip("/")
+
+
+class ModelConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    node: str
+    ollama_model: str
+    litellm_alias: str
+    context: int = Field(default=8192, gt=0)
+    timeout: int = Field(default=300, gt=0)
+    max_parallel: int = Field(default=1, gt=0)
+
+
+class AgentConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    model: str
+    description: str
+    tools: list[str] = Field(default_factory=list)
+    prompt: str | None = None
+
+    @field_validator("prompt")
+    @classmethod
+    def default_prompt(cls, value: str | None) -> str:
+        if value is None or not value.strip():
+            return DEFAULT_AGENT_PROMPT
+        return value
+
+
+class FleetConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    project: ProjectConfig
+    nodes: dict[str, NodeConfig]
+    models: dict[str, ModelConfig]
+    agents: dict[str, AgentConfig]
+
+    @model_validator(mode="after")
+    def validate_references(self) -> "FleetConfig":
+        for node_name in self.nodes:
+            if not node_name:
+                raise ValueError("node names must not be empty")
+
+        for model_name, model in self.models.items():
+            if model.node not in self.nodes:
+                raise ValueError(f"models.{model_name}.node references unknown node: {model.node}")
+
+        for agent_name, agent in self.agents.items():
+            if not AGENT_NAME_RE.fullmatch(agent_name):
+                raise ValueError(
+                    f"agents.{agent_name} must be filesystem-safe: lowercase letters, numbers, hyphens, underscores"
+                )
+            if agent.model not in self.models:
+                raise ValueError(f"agents.{agent_name}.model references unknown model: {agent.model}")
+
+        return self
+
+    def alias_warnings(self) -> list[str]:
+        aliases: dict[str, set[str]] = {}
+        for model in self.models.values():
+            aliases.setdefault(model.litellm_alias, set()).add(model.ollama_model)
+        return [
+            f"alias {alias!r} is used for multiple Ollama models: {', '.join(sorted(models))}"
+            for alias, models in sorted(aliases.items())
+            if len(models) > 1
+        ]
+
+
+def load_config(path: Path | str) -> FleetConfig:
+    config_path = Path(path)
+    try:
+        raw = yaml.load(config_path.read_text(), Loader=UniqueKeyLoader) or {}
+    except FileNotFoundError as exc:
+        raise ConfigError(f"{config_path} does not exist") from exc
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"{config_path} is not valid YAML: {exc}") from exc
+
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{config_path} must contain a YAML mapping")
+
+    try:
+        return FleetConfig.model_validate(raw)
+    except ValidationError as exc:
+        raise ConfigError(format_validation_error(exc)) from exc
+    except ValueError as exc:
+        raise ConfigError(str(exc)) from exc
+
+
+def format_validation_error(exc: ValidationError) -> str:
+    errors: list[str] = []
+    for error in exc.errors():
+        loc = ".".join(str(part) for part in error["loc"])
+        msg = error["msg"]
+        errors.append(f"{loc}: {msg}" if loc else msg)
+    return "\n".join(errors)
+
+
+def config_to_plain_dict(config: FleetConfig) -> dict[str, Any]:
+    return config.model_dump(mode="json")

subagent_fleet/defaults.py

@@ -0,0 +1,82 @@
+STARTER_FLEET_YAML = """project:
+  name: local-dev
+  gateway:
+    provider: litellm
+    host: 127.0.0.1
+    port: 4000
+    master_key_env: LITELLM_MASTER_KEY
+
+nodes:
+  local-ollama:
+    endpoint: http://localhost:11434
+    tags:
+      - controller
+      - local
+      - fast
+
+models:
+  heavy-coder:
+    node: local-ollama
+    ollama_model: qwen2.5-coder:32b
+    litellm_alias: claude-sonnet-local
+    context: 32768
+    timeout: 600
+    max_parallel: 1
+
+  small-coder:
+    node: local-ollama
+    ollama_model: qwen2.5-coder:7b
+    litellm_alias: claude-haiku-local
+    context: 8192
+    timeout: 300
+    max_parallel: 1
+
+agents:
+  planner:
+    model: small-coder
+    description: Use for planning, file discovery, task decomposition, and summarization.
+    tools:
+      - Read
+      - Grep
+      - Glob
+    prompt: |
+      You are a fast local planning agent.
+      Do not edit files.
+      Return a concise response with:
+      - plan
+      - relevant files
+      - risks
+      - next recommended agent
+
+  implementer:
+    model: heavy-coder
+    description: Use for implementation, bug fixes, refactors, and patch creation.
+    tools:
+      - Read
+      - Grep
+      - Glob
+      - Edit
+      - MultiEdit
+      - Bash
+    prompt: |
+      You are a senior implementation agent.
+      Make minimal, correct changes.
+      Prefer small patches.
+      Run relevant checks when possible.
+      Explain what changed and why.
+
+  reviewer:
+    model: heavy-coder
+    description: Use after implementation to review diffs, tests, regressions, and maintainability.
+    tools:
+      - Read
+      - Grep
+      - Glob
+      - Bash
+    prompt: |
+      You are a strict code reviewer.
+      Focus on correctness, regressions, missing tests, security issues,
+      over-engineering, and maintainability.
+      Review the diff and test output.
+      Return only actionable issues.
+"""