openfix-cli 0.4.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
openfix/policy.py ADDED
@@ -0,0 +1,310 @@
1
+ """Policy-as-code: what may be fixed, by whom, within which limits, and what proof is required.
2
+
3
+ The policy is evaluated by plain code outside the model. The model never sees
4
+ findings the policy skips, and every file write it attempts is checked against
5
+ the guards here.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import re
11
+ from enum import Enum
12
+ from functools import lru_cache
13
+ from pathlib import Path
14
+ from typing import Any, Literal
15
+
16
+ import yaml
17
+ from pydantic import BaseModel, ConfigDict, Field
18
+
19
+ from .findings import Category, Finding, Severity
20
+
21
+ POLICY_FILENAMES = ("openfix.yaml", "openfix.yml", ".openfix.yaml", ".github/openfix.yaml")
22
+
23
+
24
+ class Action(str, Enum):
25
+ autofix = "autofix" # generate, verify, and open a pull request when every required check passes
26
+ propose = "propose" # generate and verify, but only write a patch + receipt for a human to apply
27
+ skip = "skip" # never sent to a model
28
+
29
+
30
+ class Strict(BaseModel):
31
+ model_config = ConfigDict(extra="forbid")
32
+
33
+
34
+ class Match(Strict):
35
+ tool: list[str] | None = None
36
+ rule: list[str] | None = None # glob on rule id
37
+ category: list[Category] | None = None
38
+ severity: list[Severity] | None = None
39
+ min_severity: Severity | None = None
40
+ cwe: list[str] | None = None
41
+ path: list[str] | None = None # glob on finding location
42
+
43
+ def matches(self, f: Finding) -> bool:
44
+ if self.tool and f.tool.lower() not in {t.lower() for t in self.tool}:
45
+ return False
46
+ if self.rule and not any(glob_match(p, f.rule_id) for p in self.rule):
47
+ return False
48
+ if self.category and f.category not in self.category:
49
+ return False
50
+ if self.severity and f.severity not in self.severity:
51
+ return False
52
+ if self.min_severity and f.severity.rank < self.min_severity.rank:
53
+ return False
54
+ if self.cwe and not set(c.upper() for c in self.cwe) & set(f.cwe):
55
+ return False
56
+ if self.path:
57
+ target = (f.location.path if f.location else None) or (f.package.manifest if f.package else None)
58
+ if not target or not any(glob_match(p, target) for p in self.path):
59
+ return False
60
+ return True
61
+
62
+
63
+ class Rule(Strict):
64
+ name: str | None = None
65
+ match: Match = Field(default_factory=Match)
66
+ action: Action
67
+ reason: str | None = None
68
+ author: str | None = None # override the author model for matching findings
69
+ require: list[str] | None = None # override verify.require
70
+
71
+
72
+ class Guards(Strict):
73
+ max_files_changed: int = 4
74
+ max_lines_changed: int = 200
75
+ protected_paths: list[str] = Field(
76
+ default_factory=lambda: [".git/**", ".github/workflows/**", "**/.env", "**/.env.*", "openfix.yaml"]
77
+ )
78
+ allow_test_files: bool = True # the agent may add regression tests outside the finding's file
79
+ allow_new_dependencies: bool = False
80
+
81
+
82
+ class Models(Strict):
83
+ author: str = "anthropic:claude-opus-5-5"
84
+ reviewer: str | None = None # a model from a different provider is strongly recommended
85
+ local_only_paths: list[str] = Field(default_factory=list) # findings here may only use local providers
86
+ effort: Literal["low", "medium", "high", "xhigh", "max"] | None = "high"
87
+
88
+
89
+ class Budgets(Strict):
90
+ max_turns: int = 40
91
+ max_tokens_per_fix: int = 600_000
92
+ max_usd_per_fix: float | None = 3.0
93
+ max_usd_per_run: float | None = 25.0
94
+
95
+
96
+ class Command(Strict):
97
+ command: str
98
+ timeout: int = 600
99
+
100
+
101
+ class Verify(Strict):
102
+ require: list[Literal["rescan", "tests", "regression_test", "review"]] = Field(
103
+ default_factory=lambda: ["rescan", "tests"] # type: ignore[arg-type]
104
+ )
105
+ tests: Command | None = None # auto-detected when omitted
106
+ # A preset name (semgrep, snyk-code, osv-scanner, ...) or a command, or a mapping from preset name to
107
+ # either, so each finding is rescanned by its own scanner: {semgrep: {command: ...}, snyk-code: snyk-code}
108
+ scanner: Command | str | dict[str, Command | str] | None = Field(default=None, union_mode="left_to_right")
109
+ setup: Command | None = None # e.g. "npm ci --ignore-scripts", run once before tests
110
+
111
+
112
+ class Sandbox(Strict):
113
+ backend: Literal["auto", "docker", "local"] = "auto"
114
+ image: str | None = None # defaults per detected language
115
+ network: bool = False
116
+ memory: str = "2g"
117
+ cpus: str = "2"
118
+
119
+
120
+ class PullRequests(Strict):
121
+ draft: bool = True
122
+ labels: list[str] = Field(default_factory=lambda: ["security", "openfix"])
123
+ branch_prefix: str = "openfix/"
124
+ group: Literal["per-finding", "per-rule", "single"] = "per-finding"
125
+
126
+
127
+ DEFAULT_RULES: list[dict[str, Any]] = [
128
+ {
129
+ "name": "secrets need rotation, not a code change",
130
+ "match": {"category": ["secrets"]},
131
+ "action": "skip",
132
+ "reason": "A leaked credential must be rotated; removing it from code does not revoke it.",
133
+ },
134
+ {"name": "ignore informational results", "match": {"severity": ["info"]}, "action": "skip"},
135
+ {
136
+ "name": "infrastructure changes go to a human",
137
+ "match": {"category": ["iac", "container"]},
138
+ "action": "propose",
139
+ },
140
+ {
141
+ "name": "security-sensitive code is reviewed before a PR",
142
+ "match": {"path": ["**/auth/**", "**/crypto/**", "**/*crypt*", "**/iam/**", "**/payment*/**"]},
143
+ "action": "propose",
144
+ },
145
+ {"name": "dependency upgrades", "match": {"category": ["sca"]}, "action": "autofix"},
146
+ {"name": "code findings", "match": {"category": ["sast"], "min_severity": "low"}, "action": "autofix"},
147
+ ]
148
+
149
+
150
+ class Policy(Strict):
151
+ version: int = 1
152
+ default_action: Action = Action.propose
153
+ rules: list[Rule] = Field(default_factory=lambda: [Rule.model_validate(r) for r in DEFAULT_RULES])
154
+ guards: Guards = Field(default_factory=Guards)
155
+ models: Models = Field(default_factory=Models)
156
+ budgets: Budgets = Field(default_factory=Budgets)
157
+ verify: Verify = Field(default_factory=Verify)
158
+ sandbox: Sandbox = Field(default_factory=Sandbox)
159
+ pull_requests: PullRequests = Field(default_factory=PullRequests)
160
+ pricing: dict[str, tuple[float, float]] = Field(default_factory=dict) # model -> (usd/M in, usd/M out)
161
+
162
+ # ------------------------------------------------------------------ decisions
163
+
164
+ def decide(self, f: Finding) -> Decision:
165
+ for i, rule in enumerate(self.rules):
166
+ if rule.match.matches(f):
167
+ return Decision(
168
+ finding_id=f.id,
169
+ action=rule.action,
170
+ rule=rule.name or f"rules[{i}]",
171
+ reason=rule.reason,
172
+ author=rule.author or self.models.author,
173
+ require=rule.require or list(self.verify.require),
174
+ local_only=self._local_only(f),
175
+ )
176
+ return Decision(
177
+ finding_id=f.id,
178
+ action=self.default_action,
179
+ rule="default_action",
180
+ author=self.models.author,
181
+ require=list(self.verify.require),
182
+ local_only=self._local_only(f),
183
+ )
184
+
185
+ def _local_only(self, f: Finding) -> bool:
186
+ target = f.location.path if f.location else None
187
+ return bool(target and any(glob_match(p, target) for p in self.models.local_only_paths))
188
+
189
+ def is_protected(self, rel_path: str) -> bool:
190
+ return any(glob_match(p, rel_path) for p in self.guards.protected_paths)
191
+
192
+
193
+ class Decision(BaseModel):
194
+ finding_id: str
195
+ action: Action
196
+ rule: str
197
+ reason: str | None = None
198
+ author: str
199
+ require: list[str]
200
+ local_only: bool = False
201
+
202
+
203
+ def load_policy(path: str | Path | None = None, repo: str | Path | None = None) -> tuple[Policy, Path | None]:
204
+ """Load an explicit policy file, else the first policy file found in the repo, else defaults."""
205
+ candidates: list[Path] = []
206
+ if path:
207
+ candidates = [Path(path)]
208
+ elif repo:
209
+ candidates = [Path(repo) / name for name in POLICY_FILENAMES]
210
+ for c in candidates:
211
+ if c.is_file():
212
+ data = yaml.safe_load(c.read_text(encoding="utf-8")) or {}
213
+ if not isinstance(data, dict):
214
+ raise ValueError(f"{c}: policy must be a mapping")
215
+ return Policy.model_validate(data), c
216
+ if path:
217
+ raise FileNotFoundError(f"Policy file not found: {path}")
218
+ return Policy(), None
219
+
220
+
221
+ @lru_cache(maxsize=512)
222
+ def _glob_regex(pattern: str) -> re.Pattern[str]:
223
+ out, i = "", 0
224
+ while i < len(pattern):
225
+ c = pattern[i]
226
+ if pattern.startswith("**/", i):
227
+ out += "(?:.*/)?"
228
+ i += 3
229
+ elif pattern.startswith("**", i):
230
+ out += ".*"
231
+ i += 2
232
+ elif c == "*":
233
+ out += "[^/]*"
234
+ i += 1
235
+ elif c == "?":
236
+ out += "[^/]"
237
+ i += 1
238
+ else:
239
+ out += re.escape(c)
240
+ i += 1
241
+ return re.compile(f"^{out}$", re.IGNORECASE)
242
+
243
+
244
+ def glob_match(pattern: str, value: str) -> bool:
245
+ """Glob with ``**`` support. Patterns without a slash also match the basename."""
246
+ value = value.replace("\\", "/")
247
+ while value.startswith("./"):
248
+ value = value[2:]
249
+ if _glob_regex(pattern).match(value):
250
+ return True
251
+ return "/" not in pattern and bool(_glob_regex(pattern).match(value.rsplit("/", 1)[-1]))
252
+
253
+
254
+ EXAMPLE_POLICY = """\
255
+ # OpenFix policy. Evaluated by code, never by the model.
256
+ # Docs: https://github.com/markusweldon/openfix/blob/main/docs/policy.md
257
+ version: 1
258
+ default_action: propose # autofix | propose | skip
259
+
260
+ rules: # first match wins
261
+ - name: secrets need rotation, not a code change
262
+ match: { category: [secrets] }
263
+ action: skip
264
+ - name: ignore informational results
265
+ match: { severity: [info] }
266
+ action: skip
267
+ - name: infrastructure changes go to a human
268
+ match: { category: [iac, container] }
269
+ action: propose
270
+ - name: security-sensitive code is reviewed before a PR
271
+ match: { path: ["**/auth/**", "**/crypto/**", "**/payment*/**"] }
272
+ action: propose
273
+ - name: dependency upgrades
274
+ match: { category: [sca] }
275
+ action: autofix
276
+ - name: code findings
277
+ match: { category: [sast], min_severity: low }
278
+ action: autofix
279
+
280
+ guards:
281
+ max_files_changed: 4
282
+ max_lines_changed: 200
283
+ protected_paths: [".git/**", ".github/workflows/**", "**/.env", "**/.env.*", "openfix.yaml"]
284
+ allow_new_dependencies: false
285
+
286
+ models:
287
+ author: anthropic:claude-opus-5-5 # provider:model - anthropic, openai, gemini, xai, openrouter, ollama, ...
288
+ reviewer: openai:gpt-5 # optional second opinion from a different provider
289
+ local_only_paths: [] # e.g. ["services/payments/**"] -> only local models see this code
290
+
291
+ budgets:
292
+ max_turns: 40
293
+ max_tokens_per_fix: 600000
294
+ max_usd_per_fix: 3.0
295
+ max_usd_per_run: 25.0
296
+
297
+ verify:
298
+ require: [rescan, tests] # also: regression_test, review
299
+ # tests: { command: "npm test" } # auto-detected when omitted
300
+ # scanner: semgrep # preset, { command: "... {output}" } writing SARIF to {output},
301
+ # # or per tool: { semgrep: {...}, snyk-code: snyk-code }
302
+
303
+ sandbox:
304
+ backend: auto # docker when available; "local" runs commands on this machine
305
+ network: false
306
+
307
+ pull_requests:
308
+ draft: true
309
+ labels: [security, openfix]
310
+ """
openfix/pricing.py ADDED
@@ -0,0 +1,40 @@
1
+ """Cost accounting. Token counts are always recorded; dollar amounts only when a price is known.
2
+
3
+ Add or override prices in the policy file::
4
+
5
+ pricing:
6
+ openai:gpt-5: [1.25, 10.0] # USD per million input, output tokens
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from .providers.base import Usage
12
+
13
+ # USD per million tokens (input, output). Anthropic first-party list prices.
14
+ BUILTIN: dict[str, tuple[float, float]] = {
15
+ "anthropic:claude-fable-5-1": (10.0, 50.0),
16
+ "anthropic:claude-opus-5-5": (4.0, 20.0),
17
+ "anthropic:claude-opus-5": (5.0, 25.0),
18
+ "anthropic:claude-opus-4-8": (5.0, 25.0),
19
+ "anthropic:claude-sonnet-5-5": (2.0, 10.0),
20
+ "anthropic:claude-sonnet-5": (2.0, 10.0),
21
+ "anthropic:claude-sonnet-4-6": (3.0, 15.0),
22
+ "anthropic:claude-haiku-5-5": (0.10, 0.50),
23
+ "anthropic:claude-haiku-4-5": (1.0, 5.0),
24
+ }
25
+
26
+ LOCAL = {"ollama", "vllm", "lmstudio", "scripted"}
27
+
28
+
29
+ def cost_usd(
30
+ provider: str, model: str, usage: Usage, extra: dict[str, tuple[float, float]] | None = None
31
+ ) -> float | None:
32
+ if provider in LOCAL:
33
+ return 0.0
34
+ key = f"{provider}:{model}"
35
+ price = (extra or {}).get(key) or BUILTIN.get(key)
36
+ if not price:
37
+ return None
38
+ pin, pout = price
39
+ # Cache reads are billed at roughly a tenth of the input price on most providers.
40
+ return round((usage.input_tokens * pin + usage.cache_read_tokens * pin * 0.1 + usage.output_tokens * pout) / 1e6, 4)
@@ -0,0 +1,104 @@
1
+ """Model providers. Address a model as ``provider:model``, e.g. ``anthropic:claude-opus-5-5``,
2
+ ``openai:gpt-5``, ``xai:grok-4``, ``gemini:gemini-2.5-pro``, ``openrouter:qwen/qwen3-coder``,
3
+ ``ollama:qwen2.5-coder:32b``."""
4
+
5
+ from __future__ import annotations
6
+
7
+ import importlib.util
8
+ import os
9
+
10
+ from .base import Conversation, Provider, ProviderError, ToolCall, ToolResult, ToolSpec, Turn, Usage
11
+ from .openai_compat import ENDPOINTS
12
+
13
+ __all__ = [
14
+ "Conversation",
15
+ "Provider",
16
+ "ProviderError",
17
+ "ToolCall",
18
+ "ToolResult",
19
+ "ToolSpec",
20
+ "Turn",
21
+ "Usage",
22
+ "create",
23
+ "describe_providers",
24
+ "parse_ref",
25
+ ]
26
+
27
+
28
+ def parse_ref(ref: str) -> tuple[str, str]:
29
+ if ":" not in ref:
30
+ raise ProviderError(f"Model '{ref}' must be written as provider:model, e.g. anthropic:claude-opus-5-5")
31
+ provider, model = ref.split(":", 1)
32
+ return provider.strip().lower(), model.strip()
33
+
34
+
35
+ def create(ref: str, effort: str | None = "high") -> Provider:
36
+ provider, model = parse_ref(ref)
37
+ if provider in ("anthropic", "claude"):
38
+ from .anthropic import AnthropicProvider
39
+
40
+ return AnthropicProvider(model, effort=effort)
41
+ if provider in ("gemini", "google"):
42
+ from .gemini import GeminiProvider
43
+
44
+ return GeminiProvider(model, effort=effort)
45
+ if provider == "scripted":
46
+ from .scripted import ScriptedProvider
47
+
48
+ return ScriptedProvider(model)
49
+ if provider in ENDPOINTS:
50
+ from .openai_compat import OpenAICompatProvider
51
+
52
+ return OpenAICompatProvider(provider, model, effort=effort)
53
+ known = ", ".join(["anthropic", "gemini", *ENDPOINTS])
54
+ raise ProviderError(f"Unknown provider '{provider}'. Known providers: {known}")
55
+
56
+
57
+ def describe_providers() -> list[dict[str, str]]:
58
+ def sdk(mod: str) -> bool:
59
+ try:
60
+ return importlib.util.find_spec(mod) is not None
61
+ except ModuleNotFoundError:
62
+ return False
63
+
64
+ rows = [
65
+ {
66
+ "provider": "anthropic",
67
+ "example": "anthropic:claude-opus-5-5",
68
+ "sdk": "yes" if sdk("anthropic") else "pip install 'openfix[anthropic]'",
69
+ "credentials": "ANTHROPIC_API_KEY" + (" (set)" if os.environ.get("ANTHROPIC_API_KEY") else ""),
70
+ },
71
+ {
72
+ "provider": "gemini",
73
+ "example": "gemini:gemini-2.5-pro",
74
+ "sdk": "yes" if sdk("google.genai") else "pip install 'openfix[gemini]'",
75
+ "credentials": "GEMINI_API_KEY" + (" (set)" if os.environ.get("GEMINI_API_KEY") else ""),
76
+ },
77
+ ]
78
+ examples = {
79
+ "openai": "openai:gpt-5",
80
+ "xai": "xai:grok-4",
81
+ "openrouter": "openrouter:qwen/qwen3-coder",
82
+ "groq": "groq:moonshotai/kimi-k2-instruct",
83
+ "deepseek": "deepseek:deepseek-chat",
84
+ "mistral": "mistral:devstral-medium-latest",
85
+ "together": "together:Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8",
86
+ "fireworks": "fireworks:accounts/fireworks/models/qwen3-coder-480b-a35b-instruct",
87
+ "ollama": "ollama:qwen2.5-coder:32b",
88
+ "vllm": "vllm:<served-model-name>",
89
+ "lmstudio": "lmstudio:<model>",
90
+ "compat": "compat:<model> (OPENFIX_COMPAT_BASE_URL)",
91
+ }
92
+ for name, ep in ENDPOINTS.items():
93
+ cred = "none (local)" if ep.local else (ep.key_env or "")
94
+ if ep.key_env and os.environ.get(ep.key_env):
95
+ cred += " (set)"
96
+ rows.append(
97
+ {
98
+ "provider": name,
99
+ "example": examples.get(name, f"{name}:<model>"),
100
+ "sdk": "yes" if sdk("openai") else "pip install 'openfix[openai]'",
101
+ "credentials": cred,
102
+ }
103
+ )
104
+ return rows
@@ -0,0 +1,114 @@
1
+ """Claude via the official Anthropic SDK (Messages API, manual tool loop)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import re
7
+ from typing import Any
8
+
9
+ from .base import Conversation, ProviderError, StopReason, ToolCall, ToolResult, ToolSpec, Turn, Usage, require_module
10
+
11
+ # Models that take adaptive thinking + output_config.effort.
12
+ _MODERN = re.compile(r"claude-(fable|mythos|opus-[45]-[5-9]|opus-5|sonnet-[45]-[5-9]|sonnet-5|haiku-5)")
13
+ # Models that accept the server-side refusal fallback (`fallbacks: "default"`).
14
+ _FALLBACK = re.compile(r"^claude-(fable-5-1|opus-5-5|opus-5|sonnet-5-5)$")
15
+
16
+
17
+ class AnthropicProvider:
18
+ name = "anthropic"
19
+ local = False
20
+
21
+ def __init__(self, model: str, effort: str | None = "high", max_tokens: int = 32000) -> None:
22
+ self.model = model
23
+ self.effort = effort
24
+ self.max_tokens = max_tokens
25
+ sdk = require_module("anthropic", "anthropic")
26
+ self._sdk = sdk
27
+ self._client = sdk.Anthropic(max_retries=4)
28
+
29
+ def start(self, system: str, tools: list[ToolSpec]) -> Conversation:
30
+ return _AnthropicConversation(self, system, tools)
31
+
32
+
33
+ class _AnthropicConversation:
34
+ def __init__(self, provider: AnthropicProvider, system: str, tools: list[ToolSpec]) -> None:
35
+ self.p = provider
36
+ self.system = system
37
+ self.tools = [{"name": t.name, "description": t.description, "input_schema": t.parameters} for t in tools]
38
+ self.messages: list[dict[str, Any]] = []
39
+
40
+ def _params(self) -> dict[str, Any]:
41
+ params: dict[str, Any] = {
42
+ "model": self.p.model,
43
+ "max_tokens": self.p.max_tokens,
44
+ # Stable prefix (tools + system) is cached across turns.
45
+ "system": [{"type": "text", "text": self.system, "cache_control": {"type": "ephemeral"}}],
46
+ "messages": self.messages,
47
+ }
48
+ if self.tools:
49
+ params["tools"] = self.tools
50
+ if _MODERN.search(self.p.model):
51
+ params["thinking"] = {"type": "adaptive"}
52
+ if self.p.effort:
53
+ params["output_config"] = {"effort": self.p.effort}
54
+ extra_headers: dict[str, str] = {}
55
+ extra_body: dict[str, Any] = {}
56
+ if _FALLBACK.match(self.p.model) and os.environ.get("OPENFIX_ANTHROPIC_FALLBACKS", "1") != "0":
57
+ # On a safety-classifier decline, the API re-runs the request on a suitable model.
58
+ extra_headers["anthropic-beta"] = "server-side-fallback-2026-07-01"
59
+ extra_body["fallbacks"] = "default"
60
+ if extra_headers:
61
+ params["extra_headers"] = extra_headers
62
+ if extra_body:
63
+ params["extra_body"] = extra_body
64
+ return params
65
+
66
+ def send(self, *, user: str | None = None, tool_results: list[ToolResult] | None = None) -> Turn:
67
+ content: list[dict[str, Any]] = []
68
+ for r in tool_results or []:
69
+ content.append(
70
+ {"type": "tool_result", "tool_use_id": r.call_id, "content": r.content, "is_error": r.is_error}
71
+ )
72
+ if user:
73
+ content.append({"type": "text", "text": user})
74
+ if not content:
75
+ raise ProviderError("Nothing to send")
76
+ self.messages.append({"role": "user", "content": content})
77
+
78
+ sdk = self.p._sdk
79
+ while True:
80
+ try:
81
+ with self.p._client.messages.stream(**self._params()) as stream:
82
+ response = stream.get_final_message()
83
+ except sdk.APIStatusError as exc:
84
+ raise ProviderError(f"Anthropic API error {exc.status_code}: {exc.message}") from exc
85
+ except sdk.APIConnectionError as exc:
86
+ raise ProviderError(f"Could not reach the Anthropic API: {exc}") from exc
87
+ # Replay the assistant turn unchanged (thinking blocks included).
88
+ self.messages.append({"role": "assistant", "content": response.content})
89
+ if response.stop_reason == "pause_turn":
90
+ continue
91
+ break
92
+
93
+ text = "".join(b.text for b in response.content if getattr(b, "type", "") == "text")
94
+ calls = [
95
+ ToolCall(id=b.id, name=b.name, arguments=dict(b.input or {}))
96
+ for b in response.content
97
+ if getattr(b, "type", "") == "tool_use"
98
+ ]
99
+ u = response.usage
100
+ usage = Usage(
101
+ input_tokens=(u.input_tokens or 0) + (getattr(u, "cache_creation_input_tokens", 0) or 0),
102
+ output_tokens=u.output_tokens or 0,
103
+ cache_read_tokens=getattr(u, "cache_read_input_tokens", 0) or 0,
104
+ )
105
+ stop: StopReason = {
106
+ "tool_use": "tool_use",
107
+ "end_turn": "end",
108
+ "stop_sequence": "end",
109
+ "max_tokens": "max_tokens",
110
+ "refusal": "refusal",
111
+ }.get(response.stop_reason or "", "end") # type: ignore[assignment]
112
+ if calls:
113
+ stop = "tool_use"
114
+ return Turn(text=text, tool_calls=calls, stop=stop, usage=usage, model=getattr(response, "model", None))
@@ -0,0 +1,86 @@
1
+ """Provider-neutral conversation interface.
2
+
3
+ Each provider keeps its own native message history (so provider-specific blocks
4
+ such as Claude thinking blocks are replayed unchanged) and exposes the same
5
+ small surface to the agent loop: send text or tool results, get back text,
6
+ tool calls, a stop reason and token usage.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from dataclasses import dataclass, field
12
+ from typing import Any, Literal, Protocol
13
+
14
+ StopReason = Literal["tool_use", "end", "max_tokens", "refusal", "error"]
15
+
16
+
17
+ @dataclass
18
+ class ToolSpec:
19
+ name: str
20
+ description: str
21
+ parameters: dict[str, Any] # JSON Schema (object)
22
+
23
+
24
+ @dataclass
25
+ class ToolCall:
26
+ id: str
27
+ name: str
28
+ arguments: dict[str, Any]
29
+
30
+
31
+ @dataclass
32
+ class ToolResult:
33
+ call_id: str
34
+ name: str
35
+ content: str
36
+ is_error: bool = False
37
+
38
+
39
+ @dataclass
40
+ class Usage:
41
+ input_tokens: int = 0
42
+ output_tokens: int = 0
43
+ cache_read_tokens: int = 0
44
+
45
+ def add(self, other: Usage) -> None:
46
+ self.input_tokens += other.input_tokens
47
+ self.output_tokens += other.output_tokens
48
+ self.cache_read_tokens += other.cache_read_tokens
49
+
50
+ @property
51
+ def total(self) -> int:
52
+ return self.input_tokens + self.output_tokens
53
+
54
+
55
+ @dataclass
56
+ class Turn:
57
+ text: str
58
+ tool_calls: list[ToolCall]
59
+ stop: StopReason
60
+ usage: Usage = field(default_factory=Usage)
61
+ model: str | None = None # the model that actually served the turn (fallbacks may change it)
62
+
63
+
64
+ class Conversation(Protocol):
65
+ def send(self, *, user: str | None = None, tool_results: list[ToolResult] | None = None) -> Turn: ...
66
+
67
+
68
+ class Provider(Protocol):
69
+ name: str
70
+ model: str
71
+ local: bool # True when inference runs on infrastructure the user controls
72
+
73
+ def start(self, system: str, tools: list[ToolSpec]) -> Conversation: ...
74
+
75
+
76
+ class ProviderError(RuntimeError):
77
+ pass
78
+
79
+
80
+ def require_module(module: str, extra: str) -> Any:
81
+ try:
82
+ return __import__(module, fromlist=["_"])
83
+ except ImportError:
84
+ raise ProviderError(
85
+ f"The '{module}' package is not installed. Install it with: pip install 'openfix[{extra}]'"
86
+ ) from None