yeschef-cli 0.1.0__py3-none-any.whl

yeschef/__init__.py

@@ -0,0 +1,3 @@
+"""yeschef: task dispatch and multi-agent conversation hub."""
+
+__version__ = "0.1.0"

yeschef/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m yeschef`` (used for detached child processes)."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

yeschef/agent/__init__.py

@@ -0,0 +1,6 @@
+"""Reference harness that turns a local model endpoint into a hub agent."""
+
+from .config import AgentConfig
+from .harness import Harness, run_agent
+
+__all__ = ["AgentConfig", "Harness", "run_agent"]

yeschef/agent/backends/__init__.py

@@ -0,0 +1,53 @@
+"""Model backends for the harness."""
+
+from __future__ import annotations
+
+from .anthropic_compat import AnthropicCompatBackend
+from .base import Backend, ChatResult, ToolCall, ToolResult, Turn
+from .cli import CliBackend
+from .openai_compat import OpenAICompatBackend
+
+
+def build_backend(config: dict) -> Backend:
+    """Construct a backend from the `[backend]` block of an agent config.
+
+    `tahoma` is an OpenAI-compatible preset — Tahoma serves /v1/chat/completions, so it
+    shares the adapter and only differs in defaults.
+    """
+    kind = (config.get("type") or "openai_compat").lower()
+    if kind == "cli":
+        return CliBackend(
+            command=list(config.get("command") or []),
+            model=config.get("model", "cli-agent"),
+            timeout=float(config.get("timeout_s", 1800.0)),
+            env=dict(config.get("env") or {}),
+        )
+    common = {
+        "base_url": config["base_url"],
+        "model": config["model"],
+        "api_key": config.get("api_key"),
+        "timeout": float(config.get("timeout_s", 600.0)),
+        "extra_body": config.get("extra_body") or {},
+        "extra_headers": config.get("extra_headers") or {},
+    }
+    if kind == "anthropic_compat":
+        return AnthropicCompatBackend(**common)
+    if kind in ("openai_compat", "tahoma"):
+        backend = OpenAICompatBackend(**common)
+        if kind == "tahoma":
+            backend.name = "tahoma"
+        return backend
+    raise ValueError(f"unknown backend type: {kind}")
+
+
+__all__ = [
+    "AnthropicCompatBackend",
+    "Backend",
+    "CliBackend",
+    "ChatResult",
+    "OpenAICompatBackend",
+    "ToolCall",
+    "ToolResult",
+    "Turn",
+    "build_backend",
+]

yeschef/agent/backends/anthropic_compat.py

@@ -0,0 +1,119 @@
+"""Anthropic Messages API shape — Ollama v0.14+ serves this natively at /v1/messages.
+
+Ollama defaults to a 4,096-token context; raise it (num_ctx / OLLAMA_CONTEXT_LENGTH) or
+long task prompts are silently truncated.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .base import ChatResult, ToolCall, Turn
+
+
+class AnthropicCompatBackend:
+    name = "anthropic_compat"
+
+    def __init__(
+        self,
+        base_url: str,
+        model: str,
+        api_key: str | None = None,
+        timeout: float = 600.0,
+        extra_body: dict | None = None,
+        extra_headers: dict | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+        self.extra_body = extra_body or {}
+        headers = {"Content-Type": "application/json", "anthropic-version": "2023-06-01"}
+        if api_key:
+            headers["x-api-key"] = api_key
+        headers.update(extra_headers or {})
+        self._http = httpx.AsyncClient(headers=headers, timeout=timeout)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def chat(
+        self,
+        system: str,
+        turns: list[Turn],
+        tools: list[dict] | None = None,
+        max_tokens: int = 2048,
+        temperature: float = 0.7,
+    ) -> ChatResult:
+        messages: list[dict[str, Any]] = []
+        for turn in turns:
+            if turn.role == "assistant" and turn.tool_calls:
+                content: list[dict] = []
+                if turn.content:
+                    content.append({"type": "text", "text": turn.content})
+                content.extend(
+                    {
+                        "type": "tool_use",
+                        "id": call.id,
+                        "name": call.name,
+                        "input": call.arguments,
+                    }
+                    for call in turn.tool_calls
+                )
+                messages.append({"role": "assistant", "content": content})
+            else:
+                messages.append({"role": turn.role, "content": turn.content})
+            if turn.tool_results:
+                messages.append(
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "tool_result",
+                                "tool_use_id": result.call_id,
+                                "content": result.content,
+                                "is_error": result.is_error,
+                            }
+                            for result in turn.tool_results
+                        ],
+                    }
+                )
+
+        payload: dict[str, Any] = {
+            "model": self.model,
+            "system": system,
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+            **self.extra_body,
+        }
+        if tools:
+            payload["tools"] = [
+                {
+                    "name": tool["name"],
+                    "description": tool.get("description", ""),
+                    "input_schema": tool.get("input_schema", {"type": "object"}),
+                }
+                for tool in tools
+            ]
+
+        response = await self._http.post(f"{self.base_url}/v1/messages", json=payload)
+        response.raise_for_status()
+        data = response.json()
+
+        text_parts, calls = [], []
+        for block in data.get("content") or []:
+            if block.get("type") == "text":
+                text_parts.append(block.get("text", ""))
+            elif block.get("type") == "tool_use":
+                calls.append(
+                    ToolCall(id=block["id"], name=block["name"], arguments=block.get("input") or {})
+                )
+        usage = data.get("usage") or {}
+        return ChatResult(
+            text="".join(text_parts),
+            tool_calls=calls,
+            input_tokens=usage.get("input_tokens", 0),
+            output_tokens=usage.get("output_tokens", 0),
+            stop_reason=data.get("stop_reason"),
+        )

yeschef/agent/backends/base.py

@@ -0,0 +1,50 @@
+"""Backend protocol: one normalized chat call over any local model server."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from ...models import ToolCall, ToolResult
+
+
+@dataclass(slots=True)
+class ChatResult:
+    text: str
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    input_tokens: int = 0
+    output_tokens: int = 0
+    stop_reason: str | None = None
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+
+@dataclass(slots=True)
+class Turn:
+    """One entry of conversation history in backend-neutral form."""
+
+    role: str  # "user" | "assistant"
+    content: str = ""
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    tool_results: list[ToolResult] = field(default_factory=list)
+
+
+class Backend(Protocol):
+    name: str
+    model: str
+
+    async def chat(
+        self,
+        system: str,
+        turns: list[Turn],
+        tools: list[dict] | None = None,
+        max_tokens: int = 2048,
+        temperature: float = 0.7,
+    ) -> ChatResult: ...
+
+    async def close(self) -> None: ...
+
+
+__all__ = ["Backend", "ChatResult", "ToolCall", "ToolResult", "Turn"]

yeschef/agent/backends/cli.py

@@ -0,0 +1,99 @@
+"""Run a real coding-agent CLI as the worker's engine.
+
+The chat backends give a worker one model call plus a bounded tool loop — fine for
+drafts and triage, not for a buildout. This backend hands the whole task to an agent
+CLI (``claude -p``, opencode, aider …) running in the task's workspace, where it brings
+its own tool loop, its own depth, and its own judgment.
+
+The flagship configuration points ``claude -p`` at a local model server, so the full
+Claude Code harness runs against your own hardware:
+
+    [backend]
+    type = "cli"
+    command = ["claude", "-p", "{prompt}", "--dangerously-skip-permissions"]
+    [backend.env]
+    ANTHROPIC_BASE_URL = "http://localhost:11434"   # Ollama v0.14+ speaks Anthropic
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from .base import ChatResult, Turn
+
+DEFAULT_TIMEOUT_S = 1800.0
+MAX_OUTPUT_CHARS = 60_000
+PROMPT_PLACEHOLDER = "{prompt}"
+
+
+class CliBackend:
+    name = "cli"
+    uses_workspace = True
+
+    def __init__(
+        self,
+        command: list[str],
+        model: str = "cli-agent",
+        timeout: float = DEFAULT_TIMEOUT_S,
+        env: dict[str, str] | None = None,
+        base_url: str | None = None,  # accepted for config symmetry; unused
+        api_key: str | None = None,
+        extra_body: dict | None = None,
+    ) -> None:
+        if not command:
+            raise ValueError("cli backend needs a command")
+        if not any(PROMPT_PLACEHOLDER in part for part in command):
+            raise ValueError(f"cli backend command must contain {PROMPT_PLACEHOLDER}")
+        self.command = list(command)
+        self.model = model
+        self.timeout = timeout
+        self.env = env or {}
+        # Set per task by the harness before each call; None runs in the process cwd.
+        self.workspace: str | None = None
+
+    async def close(self) -> None:
+        return None
+
+    async def chat(
+        self,
+        system: str,
+        turns: list[Turn],
+        tools: list[dict] | None = None,
+        max_tokens: int = 2048,
+        temperature: float = 0.7,
+    ) -> ChatResult:
+        del tools, max_tokens, temperature  # the CLI agent brings its own
+        prompt = _flatten(system, turns)
+        argv = [part.replace(PROMPT_PLACEHOLDER, prompt) for part in self.command]
+
+        process = await asyncio.create_subprocess_exec(
+            *argv,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=self.workspace,
+            env={**os.environ, **self.env},
+        )
+        try:
+            stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=self.timeout)
+        except TimeoutError:
+            process.kill()
+            await process.wait()
+            raise RuntimeError(f"cli agent timed out after {self.timeout:.0f}s (killed)") from None
+
+        out = stdout.decode(errors="replace").strip()
+        if process.returncode != 0:
+            err = stderr.decode(errors="replace").strip()
+            raise RuntimeError(f"cli agent exited {process.returncode}: {(err or out)[:800]}")
+        return ChatResult(text=out[-MAX_OUTPUT_CHARS:], stop_reason="cli_exit")
+
+
+def _flatten(system: str, turns: list[Turn]) -> str:
+    """One prompt for a one-shot CLI run: instructions first, then the conversation."""
+    parts = [system.strip()] if system else []
+    for turn in turns:
+        content = (turn.content or "").strip()
+        if not content:
+            continue
+        parts.append(content if turn.role == "user" else f"(your earlier reply) {content}")
+    return "\n\n".join(parts)

yeschef/agent/backends/openai_compat.py

@@ -0,0 +1,118 @@
+"""Any OpenAI-compatible /chat/completions endpoint: vLLM, LM Studio, Ollama, Tahoma."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from .base import ChatResult, ToolCall, Turn
+
+
+class OpenAICompatBackend:
+    name = "openai_compat"
+
+    def __init__(
+        self,
+        base_url: str,
+        model: str,
+        api_key: str | None = None,
+        timeout: float = 600.0,
+        extra_body: dict | None = None,
+        extra_headers: dict | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+        self.extra_body = extra_body or {}
+        headers = {"Content-Type": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        headers.update(extra_headers or {})  # e.g. OpenRouter's HTTP-Referer / X-Title
+        self._http = httpx.AsyncClient(headers=headers, timeout=timeout)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def chat(
+        self,
+        system: str,
+        turns: list[Turn],
+        tools: list[dict] | None = None,
+        max_tokens: int = 2048,
+        temperature: float = 0.7,
+    ) -> ChatResult:
+        messages: list[dict[str, Any]] = [{"role": "system", "content": system}]
+        for turn in turns:
+            if turn.role == "assistant" and turn.tool_calls:
+                messages.append(
+                    {
+                        "role": "assistant",
+                        "content": turn.content or None,
+                        "tool_calls": [
+                            {
+                                "id": call.id,
+                                "type": "function",
+                                "function": {
+                                    "name": call.name,
+                                    "arguments": json.dumps(call.arguments),
+                                },
+                            }
+                            for call in turn.tool_calls
+                        ],
+                    }
+                )
+            else:
+                messages.append({"role": turn.role, "content": turn.content})
+            for result in turn.tool_results:
+                messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": result.call_id,
+                        "content": result.content,
+                    }
+                )
+
+        payload: dict[str, Any] = {
+            "model": self.model,
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+            **self.extra_body,
+        }
+        if tools:
+            payload["tools"] = [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": tool["name"],
+                        "description": tool.get("description", ""),
+                        "parameters": tool.get("input_schema", {"type": "object"}),
+                    },
+                }
+                for tool in tools
+            ]
+
+        response = await self._http.post(f"{self.base_url}/chat/completions", json=payload)
+        response.raise_for_status()
+        data = response.json()
+        choice = data["choices"][0]
+        message = choice.get("message", {})
+        calls = []
+        for raw in message.get("tool_calls") or []:
+            fn = raw.get("function", {})
+            try:
+                args = json.loads(fn.get("arguments") or "{}")
+            except json.JSONDecodeError:
+                args = {"_raw": fn.get("arguments")}
+            calls.append(
+                ToolCall(id=raw.get("id", fn.get("name", "call")), name=fn["name"], arguments=args)
+            )
+        usage = data.get("usage") or {}
+        return ChatResult(
+            text=message.get("content") or "",
+            tool_calls=calls,
+            input_tokens=usage.get("prompt_tokens", 0),
+            output_tokens=usage.get("completion_tokens", 0),
+            stop_reason=choice.get("finish_reason"),
+        )

yeschef/agent/config.py

@@ -0,0 +1,98 @@
+"""Agent configuration: one TOML file per agent."""
+
+from __future__ import annotations
+
+import os
+import socket
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ..models import ReplyWhen
+from ..settings import env as _settings_env
+from ..tools.executor import ToolsConfig
+
+DEFAULT_SYSTEM_PROMPT = (
+    "You are {name}, a cook in the kitchen working on node {node}. You collaborate "
+    "with Claude Code and with other local agents through a shared hub. Be direct and "
+    "concrete. When you are given a task, do the work and report the result; when you are in "
+    "a conversation, reply with substance and stop when the goal is met."
+)
+
+
+@dataclass(slots=True)
+class AgentConfig:
+    name: str
+    hub: str = "http://localhost:8787"
+    node: str = field(default_factory=socket.gethostname)
+    tags: list[str] = field(default_factory=list)
+    register_token: str | None = None
+
+    backend: dict = field(default_factory=dict)
+    system_prompt: str = DEFAULT_SYSTEM_PROMPT
+    reply_when: ReplyWhen = ReplyWhen.MENTIONED
+    max_tokens: int = 2048
+    temperature: float = 0.7
+    max_context_messages: int = 30
+    max_tool_iterations: int = 8
+    max_concurrent_tasks: int = 1
+    tools: ToolsConfig = field(default_factory=ToolsConfig)
+
+    @classmethod
+    def load(cls, path: str | Path) -> AgentConfig:
+        raw = tomllib.loads(Path(path).expanduser().read_text())
+        return cls.from_dict(raw)
+
+    @classmethod
+    def from_dict(cls, raw: dict) -> AgentConfig:
+        known = {
+            "name",
+            "hub",
+            "node",
+            "tags",
+            "register_token",
+            "backend",
+            "persona",
+            "runtime",
+            "tools",
+        }
+        for key in raw:
+            if key not in known:
+                # A misplaced key (register_token under [tools], a typo) otherwise
+                # fails much later with an error that never mentions it.
+                print(
+                    f"warning: unknown config key {key!r} ignored "
+                    f"(known: {', '.join(sorted(known))})",
+                    file=sys.stderr,
+                )
+        persona = raw.get("persona") or {}
+        runtime = raw.get("runtime") or {}
+        backend = dict(raw.get("backend") or {})
+        if "api_key_env" in backend:
+            backend["api_key"] = os.environ.get(backend.pop("api_key_env"))
+        node = raw.get("node") or socket.gethostname()
+        return cls(
+            name=raw["name"],
+            hub=raw.get("hub", "http://localhost:8787"),
+            node=node,
+            tags=list(raw.get("tags") or []),
+            register_token=raw.get("register_token") or _settings_env("REGISTER_TOKEN"),
+            backend=backend,
+            system_prompt=persona.get("system_prompt") or DEFAULT_SYSTEM_PROMPT,
+            reply_when=ReplyWhen(persona.get("reply_when", ReplyWhen.MENTIONED)),
+            max_tokens=int(runtime.get("max_tokens", 2048)),
+            temperature=float(runtime.get("temperature", 0.7)),
+            max_context_messages=int(runtime.get("max_context_messages", 30)),
+            max_tool_iterations=int(runtime.get("max_tool_iterations", 8)),
+            max_concurrent_tasks=int(runtime.get("max_concurrent_tasks", 1)),
+            tools=ToolsConfig.from_dict(raw.get("tools")),
+        )
+
+    def rendered_system_prompt(self) -> str:
+        return self.system_prompt.format(name=self.name, node=self.node)
+
+    def backend_label(self) -> str:
+        """Prefer the detected runtime name (ollama, vllm) — it is what a human means."""
+        kind = self.backend.get("runtime") or self.backend.get("type", "openai_compat")
+        return f"{kind}/{self.backend.get('model', 'unknown')}"

yeschef/agent/detect.py

@@ -0,0 +1,98 @@
+"""Find a local model server so `join` can configure itself.
+
+Probes the endpoints local runtimes conventionally listen on and reports what is there,
+so an operator can bring a worker online without hand-writing a backend config.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+PROBE_TIMEOUT_S = 1.5
+
+
+@dataclass(slots=True)
+class DetectedBackend:
+    runtime: str  # "ollama" | "vllm" | "lmstudio" | ...
+    base_url: str  # OpenAI-compatible base, e.g. http://localhost:11434/v1
+    models: list[str]
+
+    def pick_model(self, preferred: str | None) -> str | None:
+        if not self.models:
+            return preferred
+        if preferred:
+            exact = [m for m in self.models if m == preferred]
+            if exact:
+                return exact[0]
+            partial = [m for m in self.models if preferred in m]
+            if partial:
+                return partial[0]
+        return self.models[0]
+
+
+# host is filled in per probe so a worker can point at a model on another box.
+_PROBES = [
+    ("ollama", 11434, "/api/tags"),
+    ("vllm", 8000, "/v1/models"),
+    ("lmstudio", 1234, "/v1/models"),
+    ("openai_compat", 8080, "/v1/models"),  # Tahoma's usual port
+]
+
+
+def _models_from(runtime: str, payload: dict) -> list[str]:
+    if runtime == "ollama":
+        return [m.get("name") or m.get("model") for m in payload.get("models", []) if m]
+    data = payload.get("data") or []
+    return [entry.get("id") for entry in data if entry.get("id")]
+
+
+def probe(host: str = "localhost", timeout: float = PROBE_TIMEOUT_S) -> list[DetectedBackend]:
+    """Return every model server found on `host`, in priority order."""
+    found: list[DetectedBackend] = []
+    with httpx.Client(timeout=timeout) as client:
+        for runtime, port, path in _PROBES:
+            url = f"http://{host}:{port}{path}"
+            try:
+                response = client.get(url)
+                response.raise_for_status()
+                payload = response.json()
+            except (httpx.HTTPError, ValueError):
+                continue
+            models = [m for m in _models_from(runtime, payload) if m]
+            # Ollama and everything else expose an OpenAI-compatible base at /v1.
+            base = f"http://{host}:{port}/v1"
+            found.append(DetectedBackend(runtime=runtime, base_url=base, models=models))
+    return found
+
+
+def autodetect(host: str = "localhost") -> DetectedBackend | None:
+    """The single best local backend, or None if nothing is listening."""
+    candidates = probe(host)
+    return candidates[0] if candidates else None
+
+
+async def preflight(backend_config: dict) -> tuple[bool, str]:
+    """Prove a backend config actually answers before a worker commits to it.
+
+    A wrong base_url or model otherwise registers happily and only surfaces when the
+    first task fails. Returns (ok, human message).
+    """
+    from .backends import build_backend
+    from .backends.base import Turn
+
+    backend = build_backend(backend_config)
+    try:
+        result = await backend.chat(
+            "You are a health check.",
+            [Turn(role="user", content="Reply with the single word: ok")],
+            max_tokens=8,
+            temperature=0.0,
+        )
+    except Exception as exc:  # noqa: BLE001 - the whole point is to report the failure
+        return False, f"{type(exc).__name__}: {exc}"
+    finally:
+        await backend.close()
+    text = (result.text or "").strip()
+    return True, text or "(empty reply, but the endpoint answered)"