tether-sdk 0.0.2__py3-none-any.whl

tether/providers/anthropic.py

@@ -0,0 +1,135 @@
+"""Native Anthropic `/v1/messages` httpx adapter."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from tether.providers.base import (
+    ActionCall,
+    ModelResponse,
+    extract_fallback_action,
+    parse_tool_arguments,
+)
+
+
+class AnthropicProvider:
+    """Thin async adapter for Anthropic `/v1/messages`."""
+
+    def __init__(
+        self,
+        model_name: str = "claude-3-7-sonnet-latest",
+        *,
+        api_key: str | None = None,
+        workspace_id: str | None = None,
+        base_url: str | None = None,
+        max_tokens: int = 4096,
+        timeout: float = 180.0,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.model_name = model_name
+        self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY") or ""
+        self.workspace_id = workspace_id or os.environ.get("ANTHROPIC_WORKSPACE_ID") or ""
+        self.base_url = (
+            base_url or os.environ.get("ANTHROPIC_BASE_URL") or "https://api.anthropic.com"
+        ).rstrip("/")
+        self.max_tokens = max_tokens
+        self.timeout = timeout
+        self._client = client
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(timeout=self.timeout)
+        return self._client
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        if self._client is not None and not self._client.is_closed:
+            await self._client.aclose()
+
+    async def generate(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+    ) -> ModelResponse:
+        system_text = ""
+        chat_msgs: list[dict[str, str]] = []
+        for m in messages:
+            if m.get("role") == "system":
+                system_text = str(m.get("content") or "")
+            else:
+                role = "assistant" if m.get("role") == "assistant" else "user"
+                content_str = str(m.get("content") or "").strip() or "(empty)"
+                if chat_msgs and chat_msgs[-1]["role"] == role:
+                    chat_msgs[-1]["content"] = f"{chat_msgs[-1]['content']}\n\n{content_str}"
+                else:
+                    chat_msgs.append({"role": role, "content": content_str})
+
+        anthropic_tools: list[dict[str, Any]] = []
+        for t in tools:
+            fn = t.get("function") or {}
+            anthropic_tools.append(
+                {
+                    "name": fn.get("name", "act"),
+                    "description": fn.get("description", ""),
+                    "input_schema": fn.get("parameters", {"type": "object", "properties": {}}),
+                }
+            )
+        if anthropic_tools:
+            anthropic_tools[-1]["cache_control"] = {"type": "ephemeral"}
+
+        headers: dict[str, str] = {
+            "x-api-key": self.api_key,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+        }
+        if self.workspace_id:
+            headers["anthropic-workspace-id"] = self.workspace_id
+
+        payload: dict[str, Any] = {
+            "model": self.model_name,
+            "max_tokens": self.max_tokens,
+            "messages": chat_msgs,
+            "tools": anthropic_tools,
+        }
+        if system_text:
+            payload["system"] = [
+                {
+                    "type": "text",
+                    "text": system_text,
+                    "cache_control": {"type": "ephemeral"},
+                }
+            ]
+
+        client = self._get_client()
+        resp = await client.post(
+            f"{self.base_url}/v1/messages",
+            headers=headers,
+            json=payload,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        text_parts: list[str] = []
+        action: ActionCall | None = None
+        for block in data.get("content") or []:
+            btype = block.get("type")
+            if btype == "text":
+                text_parts.append(str(block.get("text") or ""))
+            elif btype == "tool_use" and action is None:
+                action = parse_tool_arguments(block.get("input") or {})
+
+        content = "\n".join(text_parts).strip()
+        if action is None and content:
+            action = extract_fallback_action(content)
+
+        usage = data.get("usage") or {}
+        prompt_tokens = (
+            int(usage.get("input_tokens") or 0)
+            + int(usage.get("cache_creation_input_tokens") or 0)
+            + int(usage.get("cache_read_input_tokens") or 0)
+            + int(usage.get("output_tokens") or 0)
+        )
+        return ModelResponse(content=content, action=action, prompt_tokens=prompt_tokens)

tether/providers/base.py

@@ -0,0 +1,136 @@
+"""Base provider protocol and 9B fallback tool-call parser."""
+
+from __future__ import annotations
+
+import ast
+import json
+import re
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+@dataclass(slots=True)
+class ActionCall:
+    cmd: str
+    stdin: str | None = None
+
+
+@dataclass(slots=True)
+class ModelResponse:
+    content: str
+    action: ActionCall | None = None
+    prompt_tokens: int = 0
+
+
+class ModelProvider(Protocol):
+    model_name: str
+
+    async def generate(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+    ) -> ModelResponse: ...
+
+
+_ACT_CALL_RE = re.compile(
+    r"act\(\s*(?P<args>.*)\s*\)",
+    re.DOTALL,
+)
+_MULTILINE_ACT_RE = re.compile(
+    r"act\(\s*(?:(?:cmd|command)\s*=\s*)?(?P<q1>\"\"\"|'''|\"|')(?P<cmd>.*?)(?P=q1)"
+    r"(?:\s*,\s*(?:stdin\s*=\s*)?(?P<q2>\"\"\"|'''|\"|')(?P<stdin>[\s\S]*)(?P=q2))?\s*\)",
+)
+_TOOL_XML_RE = re.compile(
+    r"<tool_call>\s*(?P<body>.*?)\s*</tool_call>",
+    re.DOTALL,
+)
+
+
+def parse_tool_arguments(raw_args: str | dict[str, Any]) -> ActionCall | None:
+    """Parse tool arguments from a dict or JSON string into an ActionCall."""
+    data: dict[str, Any]
+    if isinstance(raw_args, dict):
+        data = raw_args
+    else:
+        try:
+            parsed = json.loads(raw_args)
+            if not isinstance(parsed, dict):
+                return None
+            data = parsed
+        except Exception:
+            return None
+
+    # If the model called `act` with {"cmd": ..., "stdin": ...}
+    if "cmd" in data:
+        cmd = str(data.get("cmd") or "").strip()
+        stdin = str(data["stdin"]) if data.get("stdin") is not None else None
+        return ActionCall(cmd=cmd, stdin=stdin) if cmd else None
+
+    if "command" in data:
+        cmd = str(data.get("command") or "").strip()
+        stdin = str(data["stdin"]) if data.get("stdin") is not None else None
+        return ActionCall(cmd=cmd, stdin=stdin) if cmd else None
+
+    return None
+
+
+def extract_fallback_action(text: str) -> ActionCall | None:
+    """Extract an ActionCall when a small 9B model emits tool syntax inside plain text."""
+    if not text:
+        return None
+
+    # 1. Check <tool_call>...</tool_call> XML blocks (common in Qwen models)
+    xml_match = _TOOL_XML_RE.search(text)
+    if xml_match:
+        body = xml_match.group("body").strip()
+        try:
+            payload = json.loads(body)
+            if isinstance(payload, dict):
+                args = payload.get("arguments") or payload.get("parameters") or payload
+                call = parse_tool_arguments(args)
+                if call:
+                    return call
+        except Exception:
+            pass
+
+    # 2. Check raw JSON object containing "cmd"
+    if '"cmd"' in text:
+        start = text.find("{")
+        end = text.rfind("}")
+        if 0 <= start < end:
+            call = parse_tool_arguments(text[start : end + 1])
+            if call:
+                return call
+
+    # 3. Check multiline-tolerant `act("...", stdin="...")` call in text
+    ml_match = _MULTILINE_ACT_RE.search(text)
+    if ml_match:
+        cmd_str = ml_match.group("cmd").strip()
+        stdin_str = ml_match.group("stdin")
+        if cmd_str:
+            return ActionCall(cmd=cmd_str, stdin=stdin_str)
+
+    # 4. Fallback to AST parse for single-line Python-style `act(...)`
+    act_match = _ACT_CALL_RE.search(text)
+    if act_match:
+        expr = f"f({act_match.group('args')})"
+        try:
+            tree = ast.parse(expr, mode="eval")
+            if isinstance(tree.body, ast.Call):
+                cmd_val: str | None = None
+                stdin_val: str | None = None
+                if tree.body.args and isinstance(tree.body.args[0], ast.Constant):
+                    cmd_val = str(tree.body.args[0].value)
+                if len(tree.body.args) > 1 and isinstance(tree.body.args[1], ast.Constant):
+                    stdin_val = str(tree.body.args[1].value)
+                for kw in tree.body.keywords:
+                    if kw.arg in ("cmd", "command") and isinstance(kw.value, ast.Constant):
+                        cmd_val = str(kw.value.value)
+                    elif kw.arg == "stdin" and isinstance(kw.value, ast.Constant):
+                        stdin_val = str(kw.value.value)
+                if cmd_val:
+                    return ActionCall(cmd=cmd_val, stdin=stdin_val)
+        except Exception:
+            pass
+
+    return None

tether/providers/ollama.py

@@ -0,0 +1,112 @@
+"""Native Ollama `/api/chat` httpx adapter with num_ctx and keep_alive support."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from tether.providers.base import (
+    ActionCall,
+    ModelResponse,
+    extract_fallback_action,
+    parse_tool_arguments,
+)
+
+
+class OllamaProvider:
+    """Thin async adapter for Ollama `/api/chat`."""
+
+    def __init__(
+        self,
+        model_name: str = "qwen3.5:9b",
+        *,
+        host: str | None = None,
+        num_ctx: int = 8192,
+        keep_alive: str = "10m",
+        timeout: float = 120.0,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.model_name = model_name
+        self.host = (host or os.environ.get("OLLAMA_HOST") or "http://localhost:11434").rstrip("/")
+        self.num_ctx = num_ctx
+        self.keep_alive = keep_alive
+        self.timeout = timeout
+        self._client = client
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(timeout=self.timeout)
+        return self._client
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        if self._client is not None and not self._client.is_closed:
+            await self._client.aclose()
+
+    async def _resolve_installed_model(self, client: httpx.AsyncClient) -> str | None:
+        """Query Ollama `/api/tags` to find an installed Qwen (or fallback) model if 404."""
+        try:
+            resp = await client.get(f"{self.host}/api/tags")
+            resp.raise_for_status()
+            models = [str(m.get("name") or "") for m in (resp.json().get("models") or [])]
+            models = [m for m in models if m]
+            if not models:
+                return None
+            # Prefer any installed Qwen model first
+            for m in models:
+                if "qwen" in m.lower():
+                    return m
+            return models[0]
+        except Exception:
+            return None
+
+    async def generate(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+    ) -> ModelResponse:
+        payload: dict[str, Any] = {
+            "model": self.model_name,
+            "messages": messages,
+            "tools": tools,
+            "stream": False,
+            "keep_alive": self.keep_alive,
+            "options": {"num_ctx": self.num_ctx, "temperature": 0.2},
+        }
+        client = self._get_client()
+        resp = await client.post(f"{self.host}/api/chat", json=payload)
+        if resp.status_code == 404:
+            fallback = await self._resolve_installed_model(client)
+            if fallback and fallback != self.model_name:
+                self.model_name = fallback
+                payload["model"] = fallback
+                resp = await client.post(f"{self.host}/api/chat", json=payload)
+        resp.raise_for_status()
+        data = resp.json()
+
+        msg = data.get("message") or {}
+        content = str(msg.get("content") or "").strip()
+        prompt_tokens = int(data.get("prompt_eval_count") or 0) + int(data.get("eval_count") or 0)
+
+        action: ActionCall | None = None
+        tool_calls = msg.get("tool_calls") or []
+        if tool_calls:
+            first_tc = tool_calls[0]
+            fn_obj = first_tc.get("function") or {}
+            fn_name = str(fn_obj.get("name") or "")
+            raw_args = fn_obj.get("arguments") or {}
+            action = parse_tool_arguments(raw_args)
+            if action is None and fn_name and fn_name != "act":
+                # Graceful 9B fallback if model called tool name directly
+                if isinstance(raw_args, dict):
+                    arg_str = " ".join(f"--{k} {v!r}" for k, v in raw_args.items())
+                    action = ActionCall(cmd=f"{fn_name} {arg_str}".strip())
+                else:
+                    action = ActionCall(cmd=fn_name)
+
+        if action is None and content:
+            action = extract_fallback_action(content)
+
+        return ModelResponse(content=content, action=action, prompt_tokens=prompt_tokens)

tether/providers/openai.py

@@ -0,0 +1,89 @@
+"""OpenAI-compatible `/v1/chat/completions` httpx adapter (GPT, OpenRouter, vLLM, Groq)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from tether.providers.base import (
+    ActionCall,
+    ModelResponse,
+    extract_fallback_action,
+    parse_tool_arguments,
+)
+
+
+class OpenAIProvider:
+    """Thin async adapter for OpenAI-compatible `/v1/chat/completions` endpoints."""
+
+    def __init__(
+        self,
+        model_name: str = "gpt-4o-mini",
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 120.0,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.model_name = model_name
+        self.api_key = api_key or os.environ.get("OPENAI_API_KEY") or ""
+        self.base_url = (
+            base_url or os.environ.get("OPENAI_BASE_URL") or "https://api.openai.com/v1"
+        ).rstrip("/")
+        self.timeout = timeout
+        self._client = client
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(timeout=self.timeout)
+        return self._client
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        if self._client is not None and not self._client.is_closed:
+            await self._client.aclose()
+
+    async def generate(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+    ) -> ModelResponse:
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        payload: dict[str, Any] = {
+            "model": self.model_name,
+            "messages": messages,
+            "tools": tools,
+            "temperature": 0.2,
+        }
+        client = self._get_client()
+        resp = await client.post(
+            f"{self.base_url}/chat/completions",
+            headers=headers,
+            json=payload,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        choices = data.get("choices") or [{}]
+        msg = choices[0].get("message") or {}
+        content = str(msg.get("content") or "").strip()
+        usage = data.get("usage") or {}
+        prompt_tokens = int(usage.get("prompt_tokens") or 0)
+
+        action: ActionCall | None = None
+        tool_calls = msg.get("tool_calls") or []
+        if tool_calls:
+            first_tc = tool_calls[0]
+            fn_obj = first_tc.get("function") or {}
+            raw_args = fn_obj.get("arguments") or "{}"
+            action = parse_tool_arguments(raw_args)
+
+        if action is None and content:
+            action = extract_fallback_action(content)
+
+        return ModelResponse(content=content, action=action, prompt_tokens=prompt_tokens)