tether-sdk 0.2.0__tar.gz → 0.2.1__tar.gz

{tether_sdk-0.2.0 → tether_sdk-0.2.1}/AGENTS.md

@@ -148,6 +148,7 @@ tether/
 - Model identifier format: `<provider>/<model_name>` (e.g., `ollama/qwen3.5:9b`, `openai/gpt-4o-mini`, `anthropic/claude-3-7-sonnet-latest`).
 - If no provider prefix is given, defaults to `ollama/<model>`.
 - Custom SDK transports (e.g., internal corporate gateways, custom local runners, or test harnesses) can be injected via `Harness(provider=...)` or registered under a custom `<prefix>/<model>` via `register_provider(prefix, factory)`.
+- Declarative providers: `~/.tether/providers.yaml` (override with `TETHER_PROVIDERS`, never read from the workspace) maps a model-id prefix to a `kind` (`openai`, `ollama`, `anthropic` or `command`); `claude-cli/sonnet` uses the entry `claude-cli`. The `command` kind runs `argv` directly (never through a shell) with `{model}`, `{system}` and `{conversation}` placeholders, and reads the reply and usage from JSON paths. Built-in prefixes (`ollama`, `openai`, `anthropic`, `claude`) cannot be shadowed, keys are env var names (never values), and an invalid file raises `ValueError: providers.yaml: ...`. Implementation in `tether/providers/declarative.py`; docs in `docs/reference/providers.md`.
 - Environment variables:
   - `OLLAMA_HOST` (default `http://localhost:11434`); `TETHER_OLLAMA_FALLBACK=1` opts in to substituting an installed model when the requested one 404s (default: fail loudly with the installed list)
   - `OPENAI_API_KEY`, `OPENAI_BASE_URL` (default `https://api.openai.com/v1` — works with OpenRouter, vLLM, Groq, etc.)

{tether_sdk-0.2.0 → tether_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tether-sdk
-Version: 0.2.0
+Version: 0.2.1
 Summary: General-purpose, headless-first LLM-Native micro-harness for small language models
 Project-URL: Homepage, https://github.com/igormcsouza/tether
 Project-URL: Repository, https://github.com/igormcsouza/tether
@@ -282,6 +282,28 @@ codex mcp add tether -- tether mcp --workspace "$PWD"      # Codex CLI
 
 Cursor, Gemini CLI, VS Code and Claude Desktop configs, a "let your harness install it" prompt and a delegation rule for `CLAUDE.md`/`AGENTS.md` are in [Use Tether Inside Your Harness](docs/tutorial/agent-interface.md).
 
+### Any model, no code: providers.yaml
+
+Declare extra providers in `~/.tether/providers.yaml` (override the path with `TETHER_PROVIDERS`). The entry key is the model-id prefix, so `claude-cli/sonnet` uses the entry `claude-cli`. It works in `tether run`, `tether pipeline`, the SDK and `tether mcp`, and the file is never read from the workspace.
+
+Kinds: `openai`, `ollama`, `anthropic` and `command`. The `command` kind wraps any program that takes a prompt and prints JSON (a `claude -p`, `codex exec` or `gemini -p` style command), and runs `argv` directly, never through a shell. Keys are given as env var names, never values.
+
+```yaml
+claude-cli:
+  kind: command
+  argv: [claude, -p, --model, "{model}", --tools, "", --system-prompt, "{system}", --output-format, json, --no-session-persistence, --setting-sources, "", --disable-slash-commands, --strict-mcp-config]
+  stdin: "{conversation}"
+  reply: result
+  usage: {prompt: [usage.input_tokens, usage.cache_creation_input_tokens, usage.cache_read_input_tokens], completion: usage.output_tokens}
+  timeout: 180
+```
+
+```bash
+tether run --model claude-cli/sonnet "fix the failing test"
+```
+
+On one small bug-fix task (v0.2.0 test), this backend used about 15x fewer tokens than plain `claude -p` (21k vs 330k). That is a single small task, not a benchmark. See [Declarative providers](docs/reference/providers.md#declarative-providers).
+
 ### Python SDK Usage
 
 ```python

{tether_sdk-0.2.0 → tether_sdk-0.2.1}/README.md

@@ -261,6 +261,28 @@ codex mcp add tether -- tether mcp --workspace "$PWD"      # Codex CLI
 
 Cursor, Gemini CLI, VS Code and Claude Desktop configs, a "let your harness install it" prompt and a delegation rule for `CLAUDE.md`/`AGENTS.md` are in [Use Tether Inside Your Harness](docs/tutorial/agent-interface.md).
 
+### Any model, no code: providers.yaml
+
+Declare extra providers in `~/.tether/providers.yaml` (override the path with `TETHER_PROVIDERS`). The entry key is the model-id prefix, so `claude-cli/sonnet` uses the entry `claude-cli`. It works in `tether run`, `tether pipeline`, the SDK and `tether mcp`, and the file is never read from the workspace.
+
+Kinds: `openai`, `ollama`, `anthropic` and `command`. The `command` kind wraps any program that takes a prompt and prints JSON (a `claude -p`, `codex exec` or `gemini -p` style command), and runs `argv` directly, never through a shell. Keys are given as env var names, never values.
+
+```yaml
+claude-cli:
+  kind: command
+  argv: [claude, -p, --model, "{model}", --tools, "", --system-prompt, "{system}", --output-format, json, --no-session-persistence, --setting-sources, "", --disable-slash-commands, --strict-mcp-config]
+  stdin: "{conversation}"
+  reply: result
+  usage: {prompt: [usage.input_tokens, usage.cache_creation_input_tokens, usage.cache_read_input_tokens], completion: usage.output_tokens}
+  timeout: 180
+```
+
+```bash
+tether run --model claude-cli/sonnet "fix the failing test"
+```
+
+On one small bug-fix task (v0.2.0 test), this backend used about 15x fewer tokens than plain `claude -p` (21k vs 330k). That is a single small task, not a benchmark. See [Declarative providers](docs/reference/providers.md#declarative-providers).
+
 ### Python SDK Usage
 
 ```python

tether_sdk-0.2.1/docs/reference/providers.md

@@ -0,0 +1,99 @@
+# Model Providers
+
+## Structured history
+
+The harness passes neutral messages (assistant `tool_calls` with `id` and dict `arguments`, then `{"role": "tool", "tool_call_id": ...}`) to providers whose `structured_history` attribute is true, and each adapter translates: Ollama sends them as-is (plus `tool_name`), OpenAI-compatible JSON-encodes `arguments`, Anthropic maps them to `tool_use` and `tool_result` blocks (merging consecutive same-role messages). A custom provider without the attribute gets the textual `act('...')` / `Observation:` form. Adapter payloads are unit-tested with mock transports; they have not been verified live against OpenAI or Anthropic.
+
+## `tether.providers`
+
+::: tether.providers
+    options:
+      show_root_heading: false
+      members_order: source
+
+## `tether.providers.base`
+
+::: tether.providers.base
+    options:
+      show_root_heading: false
+      members_order: source
+
+Ollama: an unknown model fails with `Ollama model … not found; installed: …`. Set `TETHER_OLLAMA_FALLBACK=1` (or `OllamaProvider(fallback=True)`) to substitute an installed model instead; a warning is printed to stderr and `tether stats` records the substitute ([#21](https://github.com/igormcsouza/tether/issues/21)).
+
+## Declarative providers
+
+Add providers without writing code by declaring them in `~/.tether/providers.yaml` (override the path with the `TETHER_PROVIDERS` environment variable). The file is read only from the home directory (or `TETHER_PROVIDERS`), never from the workspace, so a cloned repo cannot plant a provider.
+
+The entry key is the model-id prefix: `claude-cli/sonnet` uses the entry named `claude-cli`, and `sonnet` is passed on as the model name. Declared providers work in `tether run`, `tether pipeline`, the Python SDK and `tether mcp`.
+
+```yaml
+claude-cli:
+  kind: command
+  argv: [claude, -p, --model, "{model}", --tools, "", --system-prompt, "{system}", --output-format, json, --no-session-persistence, --setting-sources, "", --disable-slash-commands, --strict-mcp-config]
+  stdin: "{conversation}"
+  reply: result
+  usage: {prompt: [usage.input_tokens, usage.cache_creation_input_tokens, usage.cache_read_input_tokens], completion: usage.output_tokens}
+  timeout: 180
+```
+
+```bash
+tether run --model claude-cli/sonnet "fix the failing test"
+```
+
+### Kinds
+
+| `kind` | Fields |
+|---|---|
+| `openai` | `base_url`, `api_key_env` |
+| `ollama` | `host` |
+| `anthropic` | `base_url`, `api_key_env` |
+| `command` | `argv` (list), `reply` (JSON path), optional `stdin` template, optional `usage`, optional `timeout` (seconds, default 300) |
+
+`api_key_env` is the **name** of an environment variable, never the key itself.
+
+### The `command` kind
+
+A `command` entry wraps any program that takes a prompt and prints JSON.
+
+- **Placeholders**: `{model}`, `{system}` and `{conversation}` are substituted in `argv` items and in the `stdin` template. If `stdin` is omitted it defaults to `{conversation}`.
+- **No shell**: `argv` is executed directly, never through a shell.
+- **Reply**: `reply` is a dotted path into the JSON the command prints (`result` in the example).
+- **Usage**: `usage.prompt` is a path or a list of paths (their values are summed); `usage.completion` is a path. Both are optional.
+- **Protocol**: the model must answer with a single JSON `{"cmd", "stdin"}` object. The `{system}` placeholder already contains that instruction.
+
+### Rules
+
+- The built-in prefixes `ollama`, `openai`, `anthropic` and `claude` cannot be shadowed.
+- An invalid file raises `ValueError: providers.yaml: ...` naming the offending entry.
+
+### Measured example
+
+On one small bug-fix task (v0.2.0 test), using `claude -p --tools ""` as the backend, as in the entry above, used about 15x fewer tokens than plain `claude -p` (21k vs 330k). This is a single small task, not a benchmark.
+
+## `tether.providers.ollama`
+
+::: tether.providers.ollama
+    options:
+      show_root_heading: false
+      members_order: source
+
+## `tether.providers.openai`
+
+::: tether.providers.openai
+    options:
+      show_root_heading: false
+      members_order: source
+
+## `tether.providers.anthropic`
+
+::: tether.providers.anthropic
+    options:
+      show_root_heading: false
+      members_order: source
+
+## `tether.providers.declarative`
+
+::: tether.providers.declarative
+    options:
+      show_root_heading: false
+      members_order: source

{tether_sdk-0.2.0 → tether_sdk-0.2.1}/docs/release-notes.md

@@ -1,5 +1,13 @@
 # Release Notes
 
+## v0.2.1 (2026-10-19)
+
+Add model backends without code.
+
+### Features
+
+- Declarative providers (#49): add model backends without code via `~/.tether/providers.yaml` (override with `TETHER_PROVIDERS`, never read from the workspace). Kinds `openai`, `ollama`, `anthropic` and `command` (wrap any CLI that prints JSON, run without a shell). Works in `tether run`, `tether pipeline`, the SDK and `tether mcp`. See [Declarative providers](reference/providers.md#declarative-providers).
+
 ## v0.2.0 (2026-10-19)
 
 Tether as a subagent for the harness you already use (Claude Code, Codex, Cursor, Gemini CLI, Copilot): MCP server, JSON output and exit codes (#46). See [Use Tether Inside Your Harness](tutorial/agent-interface.md).

{tether_sdk-0.2.0 → tether_sdk-0.2.1}/docs/tutorial/agent-interface.md

@@ -104,6 +104,28 @@ Use `wait: false` for long jobs, then `tether_wait` and `tether_read`.
 If status is `WAITING_INPUT`, answer with `tether_send`. Keep architecture and review for yourself.
 ```
 
+## Any model, no code: providers.yaml
+
+Tether can route to any backend you declare in `~/.tether/providers.yaml` (override the path with `TETHER_PROVIDERS`). The entry key is the model-id prefix, so `claude-cli/sonnet` uses the entry `claude-cli`. It works the same in `tether run`, `tether pipeline`, the SDK and `tether mcp`, and it is never read from the workspace.
+
+The `command` kind wraps any program that reads a prompt and prints JSON, for example a `claude -p`, `codex exec` or `gemini -p` style command (check each tool's own docs for its flags). Tether runs `argv` directly, never through a shell.
+
+```yaml
+claude-cli:
+  kind: command
+  argv: [claude, -p, --model, "{model}", --tools, "", --system-prompt, "{system}", --output-format, json, --no-session-persistence, --setting-sources, "", --disable-slash-commands, --strict-mcp-config]
+  stdin: "{conversation}"
+  reply: result
+  usage: {prompt: [usage.input_tokens, usage.cache_creation_input_tokens, usage.cache_read_input_tokens], completion: usage.output_tokens}
+  timeout: 180
+```
+
+```bash
+tether run --model claude-cli/sonnet "fix the failing test"
+```
+
+On one small bug-fix task, this backend used about 15x fewer tokens than plain `claude -p` (21k vs 330k). It is a single small task, not a benchmark. Full reference: [Declarative providers](../reference/providers.md#declarative-providers).
+
 ## Patterns
 
 **Architect / executor.** The frontier model writes the spec and the tests. `tether_run` with `verify: ["pytest -q"]` implements it with a cheap model; the gate runs in the sandbox before `done` is accepted. The parent reads back only status, steps, tokens and the digest.

tether_sdk-0.2.1/tests/providers/test_declarative.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+from tether.providers import (
+    AnthropicProvider,
+    OllamaProvider,
+    OpenAIProvider,
+    resolve_provider,
+)
+from tether.providers.base import ModelResponse
+from tether.providers.declarative import (
+    CommandProvider,
+    build_declared,
+    load_declared,
+    providers_path,
+)
+
+
+def _write(monkeypatch: pytest.MonkeyPatch, tmp_path: Path, text: str) -> Path:
+    path = tmp_path / "p.yaml"
+    path.write_text(text, encoding="utf-8")
+    monkeypatch.setenv("TETHER_PROVIDERS", str(path))
+    return path
+
+
+def test_providers_path_env(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("TETHER_PROVIDERS", str(tmp_path / "x.yaml"))
+    assert providers_path() == tmp_path / "x.yaml"
+
+
+def test_providers_path_default(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.delenv("TETHER_PROVIDERS", raising=False)
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    assert providers_path() == tmp_path / ".tether" / "providers.yaml"
+
+
+def test_missing_file(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("TETHER_PROVIDERS", str(tmp_path / "nope.yaml"))
+    assert load_declared() == {}
+
+
+def test_empty_file(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    _write(monkeypatch, tmp_path, "")
+    assert load_declared() == {}
+
+
+def test_top_level_not_mapping(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    _write(monkeypatch, tmp_path, "- a\n- b\n")
+    with pytest.raises(ValueError, match="providers.yaml"):
+        load_declared()
+
+
+def test_entry_not_mapping(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    _write(monkeypatch, tmp_path, "foo: bar\n")
+    with pytest.raises(ValueError, match="providers.yaml"):
+        load_declared()
+
+
+def test_command_kind_minimal_loads(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    _write(monkeypatch, tmp_path, "foo:\n  kind: command\n  argv: [x]\n  reply: r\n")
+    assert load_declared()["foo"]["kind"] == "command"
+
+
+def test_unknown_kind(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    _write(monkeypatch, tmp_path, "foo:\n  kind: bogus\n")
+    with pytest.raises(ValueError, match="openai, ollama, anthropic"):
+        load_declared()
+
+
+def test_missing_kind(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    _write(monkeypatch, tmp_path, "foo:\n  base_url: http://x\n")
+    with pytest.raises(ValueError, match="unknown kind"):
+        load_declared()
+
+
+@pytest.mark.parametrize("name", ["ollama", "openai", "anthropic"])
+def test_cannot_shadow_builtins(monkeypatch: pytest.MonkeyPatch, tmp_path: Path, name: str) -> None:
+    _write(monkeypatch, tmp_path, f"{name}:\n  kind: openai\n")
+    with pytest.raises(ValueError, match="shadow"):
+        load_declared()
+
+
+def test_build_openai_with_api_key_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MY_KEY", "secret")
+    cfg = {"kind": "openai", "base_url": "http://x/v1", "api_key_env": "MY_KEY"}
+    provider = build_declared(cfg, "m", num_ctx=1024)
+    assert isinstance(provider, OpenAIProvider)
+    assert provider.api_key == "secret"
+    assert provider.base_url.startswith("http://x/v1")
+
+
+def test_build_ollama(monkeypatch: pytest.MonkeyPatch) -> None:
+    cfg = {"kind": "ollama", "host": "http://h:11434"}
+    provider = build_declared(cfg, "m", num_ctx=1024)
+    assert isinstance(provider, OllamaProvider)
+
+
+def test_build_anthropic(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("A_KEY", "ak")
+    cfg = {"kind": "anthropic", "api_key_env": "A_KEY", "base_url": "http://a"}
+    provider = build_declared(cfg, "m", num_ctx=1024)
+    assert isinstance(provider, AnthropicProvider)
+    assert provider.api_key == "ak"
+
+
+def test_resolve_provider_declared(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    _write(
+        monkeypatch,
+        tmp_path,
+        "mygroq:\n  kind: openai\n  base_url: http://groq.local/v1\n",
+    )
+    provider = resolve_provider("mygroq/llama")
+    assert isinstance(provider, OpenAIProvider)
+    assert provider.model_name == "llama"
+    assert provider.base_url.startswith("http://groq.local/v1")
+
+
+def test_resolve_provider_unknown_still_raises(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    _write(monkeypatch, tmp_path, "mygroq:\n  kind: openai\n")
+    with pytest.raises(ValueError, match="Unknown model provider"):
+        resolve_provider("other/llama")
+
+
+def _script(code: str, *extra: str) -> list[str]:
+    return [sys.executable, "-c", code, *extra]
+
+
+def _run(provider: CommandProvider, messages: list[dict[str, str]] | None = None) -> ModelResponse:
+    msgs: list[dict[str, str]] = messages or [{"role": "user", "content": "hi"}]
+    return asyncio.run(provider.generate(msgs, []))  # type: ignore[arg-type]
+
+
+def test_claude_cannot_be_shadowed(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    _write(monkeypatch, tmp_path, "claude:\n  kind: openai\n")
+    with pytest.raises(ValueError, match="cannot shadow"):
+        load_declared()
+
+
+def test_command_success_with_usage() -> None:
+    code = (
+        "import json;"
+        "print(json.dumps({'r': json.dumps({'cmd': 'ls'}),"
+        " 'u': {'a': 1, 'b': 2, 'c': 5, 'bad': True}}))"
+    )
+    provider = CommandProvider(
+        "m",
+        argv=_script(code),
+        reply="r",
+        usage={"prompt": ["u.a", "u.b", "u.bad", "u.none"], "completion": "u.c"},
+    )
+    assert provider.structured_history is False
+    resp = _run(provider)
+    assert resp.action is not None
+    assert resp.action.cmd == "ls"
+    assert resp.prompt_tokens == 3
+    assert resp.completion_tokens == 5
+
+
+def test_command_usage_prompt_string_and_no_completion() -> None:
+    code = "import json; print(json.dumps({'r': 'plain', 'n': 7}))"
+    provider = CommandProvider("m", argv=_script(code), reply="r", usage={"prompt": "n"})
+    resp = _run(provider)
+    assert resp.content == "plain"
+    assert resp.action is None
+    assert resp.prompt_tokens == 7
+    assert resp.completion_tokens == 0
+
+
+def test_command_xml_reply() -> None:
+    text = '<parameter name="cmd">echo hi</parameter><parameter name="stdin">body</parameter>'
+    code = f"import json; print(json.dumps({{'r': {text!r}}}))"
+    resp = _run(CommandProvider("m", argv=_script(code), reply="r"))
+    assert resp.action is not None
+    assert resp.action.cmd == "echo hi"
+    assert resp.action.stdin == "body"
+
+
+def test_command_xml_reply_without_stdin() -> None:
+    text = '<parameter name="cmd">pwd</parameter>'
+    code = f"import json; print(json.dumps({{'r': {text!r}}}))"
+    resp = _run(CommandProvider("m", argv=_script(code), reply="r"))
+    assert resp.action is not None
+    assert resp.action.cmd == "pwd"
+    assert resp.action.stdin is None
+
+
+def test_command_missing_reply_path() -> None:
+    code = "import json; print(json.dumps({'x': 1}))"
+    resp = _run(CommandProvider("m", argv=_script(code), reply="a.b"))
+    assert resp.content == ""
+    assert resp.action is None
+    assert resp.prompt_tokens == 0
+
+
+def test_command_nonzero_exit() -> None:
+    code = "import sys; sys.stderr.write('boom'); sys.exit(3)"
+    with pytest.raises(RuntimeError, match="boom"):
+        _run(CommandProvider("m", argv=_script(code), reply="r"))
+
+
+def test_command_invalid_json() -> None:
+    code = "print('not json')"
+    with pytest.raises(RuntimeError, match="invalid JSON: not json"):
+        _run(CommandProvider("m", argv=_script(code), reply="r"))
+
+
+def test_command_timeout() -> None:
+    code = "import time; time.sleep(5)"
+    with pytest.raises(RuntimeError, match="timed out"):
+        _run(CommandProvider("m", argv=_script(code), reply="r", timeout=0.2))
+
+
+_ECHO = (
+    "import sys, json;"
+    "print(json.dumps({'r': json.dumps({'model': sys.argv[1], 'system': sys.argv[2],"
+    " 'stdin': sys.stdin.read()})}))"
+)
+
+
+def test_command_placeholders_default_stdin() -> None:
+    provider = CommandProvider("mymodel", argv=_script(_ECHO, "{model}", "{system}"), reply="r")
+    resp = _run(
+        provider,
+        [
+            {"role": "system", "content": "S1"},
+            {"role": "system", "content": "S2"},
+            {"role": "user", "content": "hello {model}"},
+            {"role": "assistant", "content": "yo"},
+        ],
+    )
+    data = json.loads(resp.content)
+    assert data["model"] == "mymodel"
+    assert data["system"].startswith("S1\nS2\n\nReply with ONLY one JSON object")
+    assert data["system"].endswith('"<optional multiline payload or null>"}')
+    assert data["stdin"] == "[user]\nhello {model}\n\n[assistant]\nyo"
+
+
+def test_command_placeholders_custom_stdin() -> None:
+    provider = CommandProvider(
+        "mm",
+        argv=_script(_ECHO, "x", "y"),
+        reply="r",
+        stdin="{model}|{system}|{conversation}",
+    )
+    resp = _run(provider, [{"role": "system", "content": "S"}, {"role": "user", "content": "u"}])
+    stdin = json.loads(resp.content)["stdin"]
+    assert stdin.startswith("mm|S\n\nReply with ONLY")
+    assert stdin.endswith("|[user]\nu")
+
+
+def test_build_command_and_load(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    _write(
+        monkeypatch,
+        tmp_path,
+        "cli:\n  kind: command\n  argv: [echo, '{model}']\n  reply: out.text\n"
+        "  stdin: '{conversation}'\n  timeout: 5\n"
+        "  usage:\n    prompt: [u.a, u.b]\n    completion: u.c\n",
+    )
+    cfg = load_declared()["cli"]
+    provider = build_declared(cfg, "m", num_ctx=1024)
+    assert isinstance(provider, CommandProvider)
+    assert provider.timeout == 5
+
+
+def test_build_command_defaults() -> None:
+    provider = build_declared({"kind": "command", "argv": ["x"], "reply": "r"}, "m", num_ctx=1024)
+    assert isinstance(provider, CommandProvider)
+    assert provider.timeout == 300
+    assert provider.stdin == "{conversation}"
+
+
+@pytest.mark.parametrize(
+    ("body", "message"),
+    [
+        ("reply: r\n", "requires `argv`"),
+        ("argv: []\n  reply: r\n", "requires `argv`"),
+        ("argv: [1]\n  reply: r\n", "requires `argv`"),
+        ("argv: [x]\n", "requires `reply`"),
+        ("argv: [x]\n  reply: 3\n", "requires `reply`"),
+        ("argv: [x]\n  reply: r\n  stdin: 3\n", "invalid `stdin`"),
+        ("argv: [x]\n  reply: r\n  timeout: abc\n", "invalid `timeout`"),
+        ("argv: [x]\n  reply: r\n  timeout: true\n", "invalid `timeout`"),
+        ("argv: [x]\n  reply: r\n  timeout: -1\n", "invalid `timeout`"),
+        ("argv: [x]\n  reply: r\n  usage: 3\n", "invalid `usage`"),
+        ("argv: [x]\n  reply: r\n  usage:\n    prompt: 3\n", "invalid `usage.prompt`"),
+        ("argv: [x]\n  reply: r\n  usage:\n    completion: [a]\n", "invalid `usage.completion`"),
+    ],
+)
+def test_command_validation_errors(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, body: str, message: str
+) -> None:
+    _write(monkeypatch, tmp_path, f"cli:\n  kind: command\n  {body}")
+    with pytest.raises(ValueError, match=f"providers.yaml: entry `cli`.*{message}"):
+        load_declared()

{tether_sdk-0.2.0 → tether_sdk-0.2.1}/tests/test_tether.py

@@ -7,6 +7,6 @@ import tether
 
 def test_version_and_public_exports() -> None:
     """Verify package __version__ and public SDK symbols."""
-    assert tether.__version__ == "0.2.0"
+    assert tether.__version__ == "0.2.1"
     for symbol in tether.__all__:
         assert hasattr(tether, symbol)

{tether_sdk-0.2.0 → tether_sdk-0.2.1}/tether/__init__.py

@@ -30,7 +30,7 @@ from tether.store import (
     ToolOffender,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 __all__ = [
     "ActionCall",

{tether_sdk-0.2.0 → tether_sdk-0.2.1}/tether/providers/__init__.py

@@ -13,6 +13,7 @@ from tether.providers.base import (
     extract_fallback_action,
     parse_tool_arguments,
 )
+from tether.providers.declarative import build_declared, load_declared
 from tether.providers.ollama import OllamaProvider
 from tether.providers.openai import OpenAIProvider
 
@@ -45,6 +46,9 @@ def resolve_provider(model: str, *, num_ctx: int = 8192) -> ModelProvider:
         return OpenAIProvider(model_name=name)
     if provider in ("anthropic", "claude"):
         return AnthropicProvider(model_name=name)
+    declared = load_declared()
+    if provider in declared:
+        return build_declared(declared[provider], name, num_ctx=num_ctx)
     supported = ["ollama/", "openai/", "anthropic/", *[f"{k}/" for k in _CUSTOM_PROVIDERS]]
     raise ValueError(
         f"Unknown model provider `{prefix}` in `{model}`. "

tether_sdk-0.2.1/tether/providers/declarative.py

@@ -0,0 +1,230 @@
+"""Declarative providers loaded from ~/.tether/providers.yaml."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from tether.providers.anthropic import AnthropicProvider
+from tether.providers.base import ActionCall, ModelProvider, ModelResponse, extract_fallback_action
+from tether.providers.ollama import OllamaProvider
+from tether.providers.openai import OpenAIProvider
+
+VALID_KINDS = ("openai", "ollama", "anthropic", "command")
+BUILTIN_PREFIXES = ("ollama", "openai", "anthropic", "claude")
+
+_SYSTEM_SUFFIX = (
+    "\n\nReply with ONLY one JSON object, no prose, no code fence: "
+    '{"cmd": "<command>", "stdin": "<optional multiline payload or null>"}'
+)
+_XML_CMD_RE = re.compile(r'<parameter name="cmd">(?P<v>.*?)</parameter>', re.DOTALL)
+_XML_STDIN_RE = re.compile(r'<parameter name="stdin">(?P<v>.*?)</parameter>', re.DOTALL)
+
+
+def providers_path() -> Path:
+    """Return the providers file path (TETHER_PROVIDERS overrides the default)."""
+    env = os.environ.get("TETHER_PROVIDERS")
+    if env:
+        return Path(env)
+    return Path.home() / ".tether" / "providers.yaml"
+
+
+def _bad(name: Any, problem: str) -> ValueError:
+    return ValueError(f"providers.yaml: entry `{name}` {problem}")
+
+
+def _is_str_list(value: Any) -> bool:
+    return isinstance(value, list) and bool(value) and all(isinstance(v, str) for v in value)
+
+
+def _validate_command(name: Any, cfg: dict[str, Any]) -> None:
+    if not _is_str_list(cfg.get("argv")):
+        raise _bad(name, "kind `command` requires `argv` (non-empty list of strings)")
+    reply = cfg.get("reply")
+    if not isinstance(reply, str) or not reply:
+        raise _bad(name, "kind `command` requires `reply` (dotted JSON path string)")
+    stdin = cfg.get("stdin")
+    if stdin is not None and not isinstance(stdin, str):
+        raise _bad(name, "has invalid `stdin` (must be a string template)")
+    timeout = cfg.get("timeout")
+    if timeout is not None and (
+        isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0
+    ):
+        raise _bad(name, "has invalid `timeout` (must be a positive number)")
+    usage = cfg.get("usage")
+    if usage is None:
+        return
+    if not isinstance(usage, dict):
+        raise _bad(name, "has invalid `usage` (must be a mapping)")
+    prompt = usage.get("prompt")
+    if prompt is not None and not (isinstance(prompt, str) or _is_str_list(prompt)):
+        raise _bad(name, "has invalid `usage.prompt` (path string or list of path strings)")
+    completion = usage.get("completion")
+    if completion is not None and not isinstance(completion, str):
+        raise _bad(name, "has invalid `usage.completion` (path string)")
+
+
+def load_declared() -> dict[str, dict[str, Any]]:
+    """Load and validate declared providers; returns {} if the file is missing."""
+    path = providers_path()
+    if not path.exists():
+        return {}
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError("providers.yaml: top level must be a mapping of name -> mapping")
+    result: dict[str, dict[str, Any]] = {}
+    for name, cfg in data.items():
+        if not isinstance(cfg, dict):
+            raise ValueError(f"providers.yaml: entry `{name}` must be a mapping")
+        if str(name).lower() in BUILTIN_PREFIXES:
+            raise ValueError(f"providers.yaml: `{name}` cannot shadow a built-in provider")
+        kind = cfg.get("kind")
+        if kind not in VALID_KINDS:
+            raise ValueError(
+                f"providers.yaml: entry `{name}` has unknown kind `{kind}`. "
+                f"Valid kinds: {', '.join(VALID_KINDS)}."
+            )
+        if kind == "command":
+            _validate_command(name, cfg)
+        result[str(name)] = cfg
+    return result
+
+
+def _lookup(data: Any, path: str) -> Any:
+    cur = data
+    for part in path.split("."):
+        if not isinstance(cur, dict) or part not in cur:
+            return None
+        cur = cur[part]
+    return cur
+
+
+def _as_int(value: Any) -> int:
+    return value if isinstance(value, int) and not isinstance(value, bool) else 0
+
+
+class CommandProvider:
+    """Provider that shells out to an external command (argv, never a shell)."""
+
+    structured_history = False
+
+    def __init__(
+        self,
+        model_name: str,
+        *,
+        argv: list[str],
+        reply: str,
+        stdin: str | None = None,
+        usage: dict[str, Any] | None = None,
+        timeout: float = 300,
+    ) -> None:
+        self.model_name = model_name
+        self.argv = argv
+        self.reply = reply
+        self.stdin = stdin if stdin is not None else "{conversation}"
+        self.usage = usage or {}
+        self.timeout = timeout
+
+    def _render(self, template: str, system: str, conversation: str) -> str:
+        return (
+            template.replace("{model}", self.model_name)
+            .replace("{system}", system)
+            .replace("{conversation}", conversation)
+        )
+
+    async def generate(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+    ) -> ModelResponse:
+        system = (
+            "\n".join(str(m.get("content", "")) for m in messages if m.get("role") == "system")
+            + _SYSTEM_SUFFIX
+        )
+        conversation = "\n\n".join(
+            f"[{m.get('role', '')}]\n{m.get('content', '')}"
+            for m in messages
+            if m.get("role") != "system"
+        )
+        argv = [self._render(a, system, conversation) for a in self.argv]
+        stdin = self._render(self.stdin, system, conversation)
+        proc = await asyncio.create_subprocess_exec(
+            *argv,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        try:
+            out, err = await asyncio.wait_for(
+                proc.communicate(stdin.encode("utf-8")), timeout=self.timeout
+            )
+        except TimeoutError:
+            proc.kill()
+            await proc.wait()
+            raise RuntimeError(
+                f"command provider `{self.model_name}` timed out after {self.timeout}s"
+            ) from None
+        out_text = out.decode("utf-8", errors="replace")
+        err_text = err.decode("utf-8", errors="replace")
+        if proc.returncode != 0:
+            raise RuntimeError(
+                f"command provider `{self.model_name}` exited with {proc.returncode}: "
+                f"{(err_text or out_text)[:300]}"
+            )
+        try:
+            payload = json.loads(out_text)
+        except json.JSONDecodeError:
+            raise RuntimeError(
+                f"command provider `{self.model_name}` returned invalid JSON: "
+                f"{(out_text or err_text)[:300]}"
+            ) from None
+        value = _lookup(payload, self.reply)
+        text = value if isinstance(value, str) else ""
+        action = extract_fallback_action(text)
+        if action is None:
+            cmd_match = _XML_CMD_RE.search(text)
+            if cmd_match:
+                stdin_match = _XML_STDIN_RE.search(text)
+                action = ActionCall(
+                    cmd=cmd_match.group("v").strip(),
+                    stdin=stdin_match.group("v") if stdin_match else None,
+                )
+        prompt_paths = self.usage.get("prompt") or []
+        if isinstance(prompt_paths, str):
+            prompt_paths = [prompt_paths]
+        completion_path = self.usage.get("completion")
+        return ModelResponse(
+            content=text,
+            action=action,
+            prompt_tokens=sum(_as_int(_lookup(payload, p)) for p in prompt_paths),
+            completion_tokens=_as_int(_lookup(payload, completion_path)) if completion_path else 0,
+        )
+
+
+def build_declared(cfg: dict[str, Any], model_name: str, *, num_ctx: int) -> ModelProvider:
+    """Build a provider instance from a declared config entry."""
+    kind = cfg["kind"]
+    if kind == "command":
+        return CommandProvider(
+            model_name,
+            argv=cfg["argv"],
+            reply=cfg["reply"],
+            stdin=cfg.get("stdin"),
+            usage=cfg.get("usage"),
+            timeout=cfg.get("timeout", 300),
+        )
+    api_key_env = cfg.get("api_key_env")
+    api_key = os.environ.get(api_key_env) if api_key_env else None
+    if kind == "openai":
+        return OpenAIProvider(model_name, api_key=api_key, base_url=cfg.get("base_url"))
+    if kind == "ollama":
+        return OllamaProvider(model_name, host=cfg.get("host"), num_ctx=num_ctx)
+    return AnthropicProvider(model_name, api_key=api_key, base_url=cfg.get("base_url"))

tether_sdk-0.2.0/docs/reference/providers.md

@@ -1,42 +0,0 @@
-# Model Providers
-
-## Structured history
-
-The harness passes neutral messages (assistant `tool_calls` with `id` and dict `arguments`, then `{"role": "tool", "tool_call_id": ...}`) to providers whose `structured_history` attribute is true, and each adapter translates: Ollama sends them as-is (plus `tool_name`), OpenAI-compatible JSON-encodes `arguments`, Anthropic maps them to `tool_use` and `tool_result` blocks (merging consecutive same-role messages). A custom provider without the attribute gets the textual `act('...')` / `Observation:` form. Adapter payloads are unit-tested with mock transports; they have not been verified live against OpenAI or Anthropic.
-
-## `tether.providers`
-
-::: tether.providers
-    options:
-      show_root_heading: false
-      members_order: source
-
-## `tether.providers.base`
-
-::: tether.providers.base
-    options:
-      show_root_heading: false
-      members_order: source
-
-Ollama: an unknown model fails with `Ollama model … not found; installed: …`. Set `TETHER_OLLAMA_FALLBACK=1` (or `OllamaProvider(fallback=True)`) to substitute an installed model instead; a warning is printed to stderr and `tether stats` records the substitute ([#21](https://github.com/igormcsouza/tether/issues/21)).
-
-## `tether.providers.ollama`
-
-::: tether.providers.ollama
-    options:
-      show_root_heading: false
-      members_order: source
-
-## `tether.providers.openai`
-
-::: tether.providers.openai
-    options:
-      show_root_heading: false
-      members_order: source
-
-## `tether.providers.anthropic`
-
-::: tether.providers.anthropic
-    options:
-      show_root_heading: false
-      members_order: source