agentos-provider-openai-compat 0.17.0__tar.gz

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.
@@ -0,0 +1,105 @@
1
+ Metadata-Version: 2.4
2
+ Name: agentos-provider-openai-compat
3
+ Version: 0.17.0
4
+ Summary: AgentOS executor for any OpenAI-compatible chat-completions server (Ollama, vLLM, LM Studio, OpenRouter, OpenAI) over plain HTTP
5
+ License: MIT
6
+ Project-URL: Repository, https://github.com/AmitSinghOM/AgentOS
7
+ Requires-Python: >=3.11
8
+ Description-Content-Type: text/markdown
9
+ Requires-Dist: dagentos[providerkit]<1.0,>=0.11
10
+ Requires-Dist: httpx>=0.27
11
+ Provides-Extra: dev
12
+ Requires-Dist: pytest>=8.0; extra == "dev"
13
+ Requires-Dist: fastapi>=0.110; extra == "dev"
14
+
15
+ # agentos-provider-openai-compat
16
+
17
+ AgentOS executor for any server that speaks the OpenAI chat-completions wire format:
18
+ **Ollama** (zero-config default), vLLM, LM Studio, OpenRouter, OpenAI. Plain `httpx`, no
19
+ vendor SDK — the wire format is the stable contract; a client library is not.
20
+
21
+ ```bash
22
+ pip install -e . -e providers/openai-compat # from the AgentOS checkout
23
+ ```
24
+
25
+ Registers the executor `openai-compat` through the `agentos.executors` entry point; the API
26
+ and worker discover it at startup and `GET /executors` shows it with a health check
27
+ (server reachable? aliases resolvable to models it actually has?).
28
+
29
+ Five-minute walkthrough with a local model: [`docs/quickstart-llm.md`](../../docs/quickstart-llm.md),
30
+ or `python scripts/quickstart_llm.py` against a running API.
31
+
32
+ ## Agent definition
33
+
34
+ ```json
35
+ {"name": "poet", "type": "llm", "executor": "openai-compat",
36
+ "config": {"model": "chat.fast",
37
+ "system": "You are a terse poet.",
38
+ "prompt": "Write a haiku about {run.topic}."}}
39
+ ```
40
+
41
+ | `config` key | meaning | default |
42
+ | --- | --- | --- |
43
+ | `model` | capability alias (`chat.fast`) or concrete id (`gpt-4o-mini`) | `chat.default` |
44
+ | `system` | system prompt | none |
45
+ | `prompt` | user-message template; `{run.x}` = run inputs, `{step.field}` = upstream output | inputs as JSON |
46
+ | `temperature` / `seed` | deterministic by default so cassettes replay | `0` / `42` |
47
+ | `max_tokens` | | server default |
48
+ | `json_output` | request a JSON object; parsed into `output.json` | `false` |
49
+
50
+ ## Environment
51
+
52
+ | variable | default | notes |
53
+ | --- | --- | --- |
54
+ | `AGENTOS_OPENAI_BASE_URL` | `http://127.0.0.1:11434/v1` | include `/v1` |
55
+ | `AGENTOS_OPENAI_API_KEY` | unset (falls back to `OPENAI_API_KEY`) | Ollama needs none |
56
+ | `AGENTOS_OPENAI_ALIASES` | `{"chat.fast": "qwen2.5:0.5b", "chat.default": "llama3.2:3b"}` | JSON, merged over the defaults |
57
+ | `AGENTOS_OPENAI_PRICING` | bundled `pricing.json` | content-addressed; hash on every step |
58
+ | `AGENTOS_OPENAI_TIMEOUT` | `60` | seconds |
59
+ | `AGENTOS_OPENAI_CASSETTES` | `off` | `replay` / `record` (tests) |
60
+ | `AGENTOS_OPENAI_CASSETTE_DIR` / `AGENTOS_OPENAI_CASSETTE` | `./cassettes` / `default` | |
61
+
62
+ A bad value raises `ConfigError` naming the variable; the API/worker log it and skip this
63
+ plugin rather than refusing to start.
64
+
65
+ ## What a step records
66
+
67
+ `output`: `text`, `model` (the id the server reports), `alias`, `finish_reason`, `usage`,
68
+ `priced`, and `json` when requested. `cost`: `input_tokens`, `output_tokens`, `requests`
69
+ meters, a Decimal `amount`, and `pricing_snapshot_hash` — the table's bytes are stored in
70
+ the BlobStore at startup (`GET /blobs/{hash}`). `provenance`: `openai-compat`, package
71
+ version, concrete `model_id`, `model_alias`, `prompt_hash`. Effects: `compute` only.
72
+
73
+ ## Aliases and substitution (§11 A3)
74
+
75
+ `resolve(req)` maps the alias to a concrete id without touching the network. If the
76
+ resolution for an agent changes *during* a run — alias re-pointed, model retired — the
77
+ engine appends `executor.substituted{from, to, reason}` before the next step. Completed
78
+ steps are never re-run.
79
+
80
+ ## Errors say what to do
81
+
82
+ | exception | when | message tells you |
83
+ | --- | --- | --- |
84
+ | `ProviderUnreachable` | connection refused | `ollama serve` / check `AGENTOS_OPENAI_BASE_URL` |
85
+ | `ModelNotFound` | 404 | `ollama pull <id>` or fix the alias |
86
+ | `AuthenticationFailed` | 401/403 | set `AGENTOS_OPENAI_API_KEY` |
87
+ | `ProviderRateLimited` / `ProviderServerError` | 429 / 5xx / timeout | the node's retry policy applies |
88
+ | `TemplateError` | `{x.y}` not in inputs | the keys that *are* available |
89
+ | `BadResponse` | malformed body or non-JSON when `json_output` | what came back |
90
+
91
+ The engine records each as `step.failed` → retries per the node's policy →
92
+ `step.dead_lettered` with the message as the cause.
93
+
94
+ ## Testing (§11 A10)
95
+
96
+ `tests/` runs against **cassettes recorded from a real Ollama** (`qwen2.5:0.5b`, see each
97
+ file's `source`), never the network. `tests/reference_server.py` fakes specific status
98
+ codes. Re-record: `python scripts/record_cassettes.py --live`. The nightly
99
+ [`provider-live`](../../.github/workflows/provider-live.yml) workflow installs Ollama on a
100
+ runner, re-records, and re-runs the replay tests on the fresh recordings. If that job fails
101
+ for 30 days this README gets a `deprecated` banner; the core is unaffected.
102
+
103
+ ## Status
104
+
105
+ `0.1.0` — first provider plugin. MIT.
@@ -0,0 +1,91 @@
1
+ # agentos-provider-openai-compat
2
+
3
+ AgentOS executor for any server that speaks the OpenAI chat-completions wire format:
4
+ **Ollama** (zero-config default), vLLM, LM Studio, OpenRouter, OpenAI. Plain `httpx`, no
5
+ vendor SDK — the wire format is the stable contract; a client library is not.
6
+
7
+ ```bash
8
+ pip install -e . -e providers/openai-compat # from the AgentOS checkout
9
+ ```
10
+
11
+ Registers the executor `openai-compat` through the `agentos.executors` entry point; the API
12
+ and worker discover it at startup and `GET /executors` shows it with a health check
13
+ (server reachable? aliases resolvable to models it actually has?).
14
+
15
+ Five-minute walkthrough with a local model: [`docs/quickstart-llm.md`](../../docs/quickstart-llm.md),
16
+ or `python scripts/quickstart_llm.py` against a running API.
17
+
18
+ ## Agent definition
19
+
20
+ ```json
21
+ {"name": "poet", "type": "llm", "executor": "openai-compat",
22
+ "config": {"model": "chat.fast",
23
+ "system": "You are a terse poet.",
24
+ "prompt": "Write a haiku about {run.topic}."}}
25
+ ```
26
+
27
+ | `config` key | meaning | default |
28
+ | --- | --- | --- |
29
+ | `model` | capability alias (`chat.fast`) or concrete id (`gpt-4o-mini`) | `chat.default` |
30
+ | `system` | system prompt | none |
31
+ | `prompt` | user-message template; `{run.x}` = run inputs, `{step.field}` = upstream output | inputs as JSON |
32
+ | `temperature` / `seed` | deterministic by default so cassettes replay | `0` / `42` |
33
+ | `max_tokens` | | server default |
34
+ | `json_output` | request a JSON object; parsed into `output.json` | `false` |
35
+
36
+ ## Environment
37
+
38
+ | variable | default | notes |
39
+ | --- | --- | --- |
40
+ | `AGENTOS_OPENAI_BASE_URL` | `http://127.0.0.1:11434/v1` | include `/v1` |
41
+ | `AGENTOS_OPENAI_API_KEY` | unset (falls back to `OPENAI_API_KEY`) | Ollama needs none |
42
+ | `AGENTOS_OPENAI_ALIASES` | `{"chat.fast": "qwen2.5:0.5b", "chat.default": "llama3.2:3b"}` | JSON, merged over the defaults |
43
+ | `AGENTOS_OPENAI_PRICING` | bundled `pricing.json` | content-addressed; hash on every step |
44
+ | `AGENTOS_OPENAI_TIMEOUT` | `60` | seconds |
45
+ | `AGENTOS_OPENAI_CASSETTES` | `off` | `replay` / `record` (tests) |
46
+ | `AGENTOS_OPENAI_CASSETTE_DIR` / `AGENTOS_OPENAI_CASSETTE` | `./cassettes` / `default` | |
47
+
48
+ A bad value raises `ConfigError` naming the variable; the API/worker log it and skip this
49
+ plugin rather than refusing to start.
50
+
51
+ ## What a step records
52
+
53
+ `output`: `text`, `model` (the id the server reports), `alias`, `finish_reason`, `usage`,
54
+ `priced`, and `json` when requested. `cost`: `input_tokens`, `output_tokens`, `requests`
55
+ meters, a Decimal `amount`, and `pricing_snapshot_hash` — the table's bytes are stored in
56
+ the BlobStore at startup (`GET /blobs/{hash}`). `provenance`: `openai-compat`, package
57
+ version, concrete `model_id`, `model_alias`, `prompt_hash`. Effects: `compute` only.
58
+
59
+ ## Aliases and substitution (§11 A3)
60
+
61
+ `resolve(req)` maps the alias to a concrete id without touching the network. If the
62
+ resolution for an agent changes *during* a run — alias re-pointed, model retired — the
63
+ engine appends `executor.substituted{from, to, reason}` before the next step. Completed
64
+ steps are never re-run.
65
+
66
+ ## Errors say what to do
67
+
68
+ | exception | when | message tells you |
69
+ | --- | --- | --- |
70
+ | `ProviderUnreachable` | connection refused | `ollama serve` / check `AGENTOS_OPENAI_BASE_URL` |
71
+ | `ModelNotFound` | 404 | `ollama pull <id>` or fix the alias |
72
+ | `AuthenticationFailed` | 401/403 | set `AGENTOS_OPENAI_API_KEY` |
73
+ | `ProviderRateLimited` / `ProviderServerError` | 429 / 5xx / timeout | the node's retry policy applies |
74
+ | `TemplateError` | `{x.y}` not in inputs | the keys that *are* available |
75
+ | `BadResponse` | malformed body or non-JSON when `json_output` | what came back |
76
+
77
+ The engine records each as `step.failed` → retries per the node's policy →
78
+ `step.dead_lettered` with the message as the cause.
79
+
80
+ ## Testing (§11 A10)
81
+
82
+ `tests/` runs against **cassettes recorded from a real Ollama** (`qwen2.5:0.5b`, see each
83
+ file's `source`), never the network. `tests/reference_server.py` fakes specific status
84
+ codes. Re-record: `python scripts/record_cassettes.py --live`. The nightly
85
+ [`provider-live`](../../.github/workflows/provider-live.yml) workflow installs Ollama on a
86
+ runner, re-records, and re-runs the replay tests on the fresh recordings. If that job fails
87
+ for 30 days this README gets a `deprecated` banner; the core is unaffected.
88
+
89
+ ## Status
90
+
91
+ `0.1.0` — first provider plugin. MIT.
@@ -0,0 +1,33 @@
1
+ """agentos-provider-openai-compat — AgentOS executor for any OpenAI-compatible server.
2
+
3
+ Zero-config default: a local Ollama at http://127.0.0.1:11434/v1, no API key. See
4
+ `config.py` for every environment variable and `executor.py` for the agent config keys.
5
+ """
6
+ from dagentos.providerkit import (
7
+ AuthenticationFailed,
8
+ BadResponse,
9
+ ConfigError,
10
+ ModelNotFound,
11
+ ProviderConfig,
12
+ ProviderError,
13
+ ProviderRateLimited,
14
+ ProviderServerError,
15
+ ProviderUnreachable,
16
+ TemplateError,
17
+ )
18
+
19
+ from .config import from_env
20
+ from .executor import OpenAICompatExecutor
21
+
22
+ __all__ = [
23
+ "AuthenticationFailed", "BadResponse", "ConfigError", "ModelNotFound",
24
+ "OpenAICompatExecutor", "ProviderConfig", "ProviderError", "ProviderRateLimited",
25
+ "ProviderServerError", "ProviderUnreachable", "TemplateError", "from_env", "load",
26
+ ]
27
+
28
+
29
+ def load() -> OpenAICompatExecutor:
30
+ """Entry-point target for the `agentos.executors` group: configured from the
31
+ environment. A bad variable raises ConfigError naming it; the API/worker log that
32
+ and skip this plugin rather than refusing to start."""
33
+ return OpenAICompatExecutor(from_env())
@@ -0,0 +1,39 @@
1
+ """Configuration for the OpenAI-compatible provider. Every knob is an environment
2
+ variable with a documented default (see `dagentos.providerkit.config`); the zero-config
3
+ default talks to a local Ollama.
4
+
5
+ AGENTOS_OPENAI_BASE_URL http://127.0.0.1:11434/v1 any /v1 chat-completions server
6
+ AGENTOS_OPENAI_API_KEY (unset) falls back to OPENAI_API_KEY;
7
+ Ollama needs none
8
+ AGENTOS_OPENAI_ALIASES {"chat.fast": "qwen2.5:0.5b", "chat.default": "llama3.2:3b"}
9
+ AGENTOS_OPENAI_PRICING (bundled pricing.json)
10
+ AGENTOS_OPENAI_TIMEOUT 60
11
+ AGENTOS_OPENAI_CASSETTES off | replay | record
12
+ AGENTOS_OPENAI_CASSETTE_DIR / AGENTOS_OPENAI_CASSETTE
13
+ """
14
+ from __future__ import annotations
15
+
16
+ from pathlib import Path
17
+
18
+ from dagentos.providerkit.config import ConfigError, ProviderConfig, config_from_env
19
+
20
+ __all__ = ["BUNDLED_PRICING", "DEFAULT_ALIASES", "DEFAULT_BASE_URL", "ConfigError",
21
+ "ProviderConfig", "from_env"]
22
+
23
+ PREFIX = "AGENTOS_OPENAI"
24
+ DEFAULT_BASE_URL = "http://127.0.0.1:11434/v1"
25
+ DEFAULT_ALIASES: dict[str, str] = {
26
+ "chat.fast": "qwen2.5:0.5b", # ~400 MB, answers in a second on a laptop
27
+ "chat.default": "llama3.2:3b",
28
+ }
29
+ BUNDLED_PRICING = Path(__file__).with_name("pricing.json")
30
+
31
+
32
+ def from_env(env: dict[str, str] | None = None) -> ProviderConfig:
33
+ return config_from_env(PREFIX, default_base_url=DEFAULT_BASE_URL,
34
+ default_aliases=DEFAULT_ALIASES, bundled_pricing=BUNDLED_PRICING,
35
+ key_fallbacks=("OPENAI_API_KEY",), env=env)
36
+
37
+
38
+ def default() -> ProviderConfig:
39
+ return from_env({})
@@ -0,0 +1,239 @@
1
+ """The executor: one `POST {base_url}/chat/completions` per step, over plain HTTP.
2
+
3
+ No vendor SDK on purpose (docs/DEVELOPMENT_STRUCTURE.md §11 A10): the OpenAI
4
+ chat-completions wire format is the de facto protocol that Ollama, vLLM, LM Studio,
5
+ OpenRouter and OpenAI itself all speak, and a documented JSON shape outlives any client
6
+ library. Everything the core needs — output, metered cost, provenance — is derived from
7
+ the response body.
8
+
9
+ Agent `config` keys (all optional):
10
+ model capability alias ("chat.fast") or concrete id ("gpt-4o-mini");
11
+ default "chat.default"
12
+ system system prompt
13
+ prompt user-message template; `{run.topic}` reads run inputs, `{summarise.text}`
14
+ reads the upstream step "summarise"'s output field "text". Without a
15
+ template the inputs are sent as JSON.
16
+ temperature default 0 — deterministic by default so cassettes replay
17
+ seed default 42 (honoured by Ollama and OpenAI; ignored by servers without it)
18
+ max_tokens server default when unset
19
+ json_output true → ask for a JSON object and parse it into output["json"]
20
+ """
21
+ from __future__ import annotations
22
+
23
+ import hashlib
24
+ import json
25
+ from importlib.metadata import PackageNotFoundError
26
+ from importlib.metadata import version as _dist_version
27
+ from typing import Any
28
+
29
+ import httpx
30
+
31
+ from dagentos.core.models import Cost, Effect, EffectClass, Provenance, StepRequest, StepResult
32
+ from dagentos.core.ports import ProgressFn
33
+ from dagentos.providerkit.cassette import Cassette, CassetteTransport
34
+ from dagentos.providerkit.config import ProviderConfig
35
+ from dagentos.providerkit.errors import (
36
+ AuthenticationFailed,
37
+ BadResponse,
38
+ ModelNotFound,
39
+ ProviderRateLimited,
40
+ ProviderServerError,
41
+ ProviderUnreachable,
42
+ server_message,
43
+ )
44
+ from dagentos.providerkit.pricing import PricingTable
45
+ from dagentos.providerkit.prompt import DATA_BOUNDARY, render_prompt, wrap_input
46
+
47
+ from .config import from_env
48
+
49
+ NAME = "openai-compat"
50
+ try:
51
+ VERSION = _dist_version("agentos-provider-openai-compat")
52
+ except PackageNotFoundError: # running from a source tree without install
53
+ VERSION = "0.0.0+src"
54
+
55
+
56
+ # ------------------------------------------------------------------ the executor
57
+
58
+ class OpenAICompatExecutor:
59
+ name = NAME
60
+ version = VERSION
61
+
62
+ def __init__(self, config: ProviderConfig | None = None, *,
63
+ transport: httpx.BaseTransport | None = None, cassette_name: str | None = None):
64
+ self.config = config or from_env()
65
+ self.pricing = PricingTable(self.config.pricing_path)
66
+ self._transport = transport
67
+ self._cassette_name = cassette_name or self.config.cassette_name
68
+
69
+ # -- hooks the composition root and engine look for (all optional in the port) -----
70
+
71
+ def resolve(self, req: StepRequest) -> str:
72
+ """§11 A3: the concrete model this request would run on. Pure table lookup — no
73
+ network — so the engine can record a substitution before dispatch."""
74
+ return self.config.resolve(req.agent.config.get("model", "chat.default"))[0]
75
+
76
+ def describe(self) -> dict:
77
+ return {
78
+ "base_url": self.config.base_url,
79
+ "aliases": dict(self.config.aliases),
80
+ "pricing": {"sha256": self.pricing.sha256, "as_of": self.pricing.data.get("as_of"),
81
+ "path": str(self.pricing.path)},
82
+ "api_key": "set" if self.config.api_key else "unset",
83
+ "cassettes": self.config.cassettes,
84
+ }
85
+
86
+ def health(self) -> dict:
87
+ """Can we reach the server, and does it have the models our aliases point at?"""
88
+ try:
89
+ with self._client(timeout=3.0) as c:
90
+ r = c.get("/models")
91
+ r.raise_for_status()
92
+ ids = [m.get("id") for m in r.json().get("data", []) if isinstance(m, dict)]
93
+ except httpx.ConnectError as exc:
94
+ return {"reachable": False, "error": str(exc),
95
+ "hint": self._unreachable_hint()}
96
+ except Exception as exc: # noqa: BLE001 — health is a report, not a raise
97
+ return {"reachable": False, "error": str(exc)}
98
+ return {
99
+ "reachable": True,
100
+ "models": ids[:50],
101
+ "aliases_available": {a: (m in ids) for a, m in self.config.aliases.items()},
102
+ }
103
+
104
+ def pricing_snapshot(self) -> bytes:
105
+ return self.pricing.snapshot()
106
+
107
+ # -- the port -----------------------------------------------------------------------
108
+
109
+ def execute(self, req: StepRequest, progress: ProgressFn) -> StepResult:
110
+ cfg = req.agent.config
111
+ model_id, alias = self.config.resolve(cfg.get("model", "chat.default"))
112
+ messages = self._messages(cfg, req.inputs)
113
+ body: dict[str, Any] = {
114
+ "model": model_id,
115
+ "messages": messages,
116
+ "temperature": cfg.get("temperature", 0),
117
+ "seed": cfg.get("seed", 42),
118
+ }
119
+ if cfg.get("max_tokens") is not None:
120
+ body["max_tokens"] = cfg["max_tokens"]
121
+ if cfg.get("json_output"):
122
+ body["response_format"] = {"type": "json_object"}
123
+ prompt_hash = hashlib.sha256(
124
+ json.dumps(messages, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
125
+
126
+ progress(0.0, f"POST {self.config.base_url}/chat/completions model={model_id}")
127
+ data = self._post_chat(body, model_id)
128
+ try:
129
+ choice = data["choices"][0]
130
+ text = choice["message"].get("content") or ""
131
+ finish = choice.get("finish_reason")
132
+ except (KeyError, IndexError, TypeError) as exc:
133
+ raise BadResponse(f"{self.config.base_url} returned a chat completion without "
134
+ f"choices[0].message: {str(data)[:200]}") from exc
135
+ usage = data.get("usage") or {}
136
+ in_tok = int(usage.get("prompt_tokens", 0))
137
+ out_tok = int(usage.get("completion_tokens", 0))
138
+ served_model = data.get("model") or model_id
139
+ cost, priced = self.pricing.cost(served_model, in_tok, out_tok)
140
+ progress(1.0, f"{in_tok}+{out_tok} tokens, {cost.amount} {cost.currency}")
141
+
142
+ output: dict[str, Any] = {
143
+ "text": text, "model": served_model, "finish_reason": finish,
144
+ "usage": {"input_tokens": in_tok, "output_tokens": out_tok}, "priced": priced,
145
+ }
146
+ if alias:
147
+ output["alias"] = alias
148
+ if cfg.get("json_output"):
149
+ try:
150
+ output["json"] = json.loads(text)
151
+ except ValueError as exc:
152
+ raise BadResponse(f"json_output requested but {served_model} returned "
153
+ f"non-JSON: {text[:120]!r}") from exc
154
+ return StepResult(
155
+ output=output,
156
+ effects=[Effect(effect_class=EffectClass.compute,
157
+ description=f"chat completion on {served_model}")],
158
+ cost=cost if isinstance(cost, Cost) else Cost(),
159
+ provenance=Provenance(executor=self.name, executor_version=self.version,
160
+ model_id=served_model, model_alias=alias,
161
+ prompt_hash=prompt_hash),
162
+ )
163
+
164
+ # -- internals ----------------------------------------------------------------------
165
+
166
+ def _messages(self, cfg: dict, inputs: dict) -> list[dict]:
167
+ # C12: the agent definition is the only source of instructions; everything
168
+ # interpolated from inputs is delimited data and the system prompt says so.
169
+ system = f"{cfg['system']}\n\n{DATA_BOUNDARY}" if cfg.get("system") else DATA_BOUNDARY
170
+ msgs = [{"role": "system", "content": system}]
171
+ if cfg.get("prompt"):
172
+ user = render_prompt(str(cfg["prompt"]), inputs)
173
+ elif inputs:
174
+ user = wrap_input("inputs", json.dumps(inputs, sort_keys=True, ensure_ascii=False))
175
+ else:
176
+ user = "Hello."
177
+ msgs.append({"role": "user", "content": user})
178
+ return msgs
179
+
180
+ def _client(self, timeout: float | None = None) -> httpx.Client:
181
+ headers = {"content-type": "application/json", "user-agent": f"agentos-{NAME}/{VERSION}"}
182
+ if self.config.api_key:
183
+ headers["authorization"] = f"Bearer {self.config.api_key}"
184
+ transport = self._transport
185
+ if self.config.cassettes != "off":
186
+ cassette = Cassette(self.config.cassette_dir / f"{self._cassette_name}.json",
187
+ source=self.config.base_url)
188
+ transport = CassetteTransport(cassette, self.config.cassettes, inner=transport,
189
+ record_var="AGENTOS_OPENAI_CASSETTES")
190
+ return httpx.Client(base_url=self.config.base_url, headers=headers,
191
+ timeout=timeout or self.config.timeout_seconds, transport=transport)
192
+
193
+ def _post_chat(self, body: dict, model_id: str) -> dict:
194
+ try:
195
+ with self._client() as c:
196
+ r = c.post("/chat/completions", json=body)
197
+ except httpx.ConnectError as exc:
198
+ raise ProviderUnreachable(
199
+ f"cannot reach {self.config.base_url} ({exc}). {self._unreachable_hint()}") from exc
200
+ except httpx.TimeoutException as exc:
201
+ raise ProviderServerError(
202
+ f"{self.config.base_url} did not answer within {self.config.timeout_seconds}s "
203
+ f"for model {model_id!r}; raise AGENTOS_OPENAI_TIMEOUT or pick a smaller model "
204
+ f"(the step's retry policy applies)") from exc
205
+ if r.status_code == 401 or r.status_code == 403:
206
+ raise AuthenticationFailed(
207
+ f"{self.config.base_url} rejected the credentials (HTTP {r.status_code}). "
208
+ f"Set AGENTOS_OPENAI_API_KEY (or OPENAI_API_KEY); key is currently "
209
+ f"{'set' if self.config.api_key else 'unset'}. {server_message(r)}")
210
+ if r.status_code == 404:
211
+ raise ModelNotFound(
212
+ f"{self.config.base_url} has no model {model_id!r}. If this is Ollama: "
213
+ f"`ollama pull {model_id}`; otherwise fix the alias in AGENTOS_OPENAI_ALIASES "
214
+ f"or the agent's config.model. {server_message(r)}")
215
+ if r.status_code == 429:
216
+ raise ProviderRateLimited(
217
+ f"{self.config.base_url} rate-limited the request (HTTP 429); the step's retry "
218
+ f"policy applies. {server_message(r)}")
219
+ if r.status_code >= 500:
220
+ raise ProviderServerError(
221
+ f"{self.config.base_url} failed (HTTP {r.status_code}); the step's retry "
222
+ f"policy applies. {server_message(r)}")
223
+ if r.status_code >= 400:
224
+ raise BadResponse(f"{self.config.base_url} rejected the request (HTTP "
225
+ f"{r.status_code}). {server_message(r)}")
226
+ try:
227
+ return r.json()
228
+ except ValueError as exc:
229
+ raise BadResponse(f"{self.config.base_url} returned non-JSON: "
230
+ f"{r.text[:200]!r}") from exc
231
+
232
+ def _unreachable_hint(self) -> str:
233
+ if "11434" in self.config.base_url:
234
+ return ("Is Ollama running? Start it with `ollama serve` (install: "
235
+ "https://ollama.com/download), or point AGENTOS_OPENAI_BASE_URL at another "
236
+ "OpenAI-compatible server.")
237
+ return "Check AGENTOS_OPENAI_BASE_URL (include the /v1 suffix) and that the server is up."
238
+
239
+
@@ -0,0 +1,17 @@
1
+ {
2
+ "schema": "agentos.pricing/1",
3
+ "as_of": "2025-06",
4
+ "currency": "USD",
5
+ "unit": "per_1m_tokens",
6
+ "note": "Snapshot used to price steps; its sha256 is recorded on every step as cost.pricing_snapshot_hash and the bytes are stored in the BlobStore at startup, so a charge is explainable after prices change. Models not listed are priced 0 and marked priced=false in the step output. Override with AGENTOS_OPENAI_PRICING=/path/to/pricing.json.",
7
+ "models": {
8
+ "gpt-4o-mini": {"input": "0.15", "output": "0.60"},
9
+ "gpt-4o": {"input": "2.50", "output": "10.00"},
10
+ "gpt-4.1": {"input": "2.00", "output": "8.00"},
11
+ "gpt-4.1-mini": {"input": "0.40", "output": "1.60"},
12
+ "gpt-4.1-nano": {"input": "0.10", "output": "0.40"},
13
+ "o3-mini": {"input": "1.10", "output": "4.40"}
14
+ },
15
+ "free_prefixes": ["qwen", "llama", "gemma", "mistral", "phi", "deepseek", "smollm", "tinyllama"],
16
+ "free_prefixes_note": "Locally served open-weight families (Ollama, vLLM) are priced 0 and marked priced=true: running them costs electricity, not an invoice."
17
+ }
@@ -0,0 +1,105 @@
1
+ Metadata-Version: 2.4
2
+ Name: agentos-provider-openai-compat
3
+ Version: 0.17.0
4
+ Summary: AgentOS executor for any OpenAI-compatible chat-completions server (Ollama, vLLM, LM Studio, OpenRouter, OpenAI) over plain HTTP
5
+ License: MIT
6
+ Project-URL: Repository, https://github.com/AmitSinghOM/AgentOS
7
+ Requires-Python: >=3.11
8
+ Description-Content-Type: text/markdown
9
+ Requires-Dist: dagentos[providerkit]<1.0,>=0.11
10
+ Requires-Dist: httpx>=0.27
11
+ Provides-Extra: dev
12
+ Requires-Dist: pytest>=8.0; extra == "dev"
13
+ Requires-Dist: fastapi>=0.110; extra == "dev"
14
+
15
+ # agentos-provider-openai-compat
16
+
17
+ AgentOS executor for any server that speaks the OpenAI chat-completions wire format:
18
+ **Ollama** (zero-config default), vLLM, LM Studio, OpenRouter, OpenAI. Plain `httpx`, no
19
+ vendor SDK — the wire format is the stable contract; a client library is not.
20
+
21
+ ```bash
22
+ pip install -e . -e providers/openai-compat # from the AgentOS checkout
23
+ ```
24
+
25
+ Registers the executor `openai-compat` through the `agentos.executors` entry point; the API
26
+ and worker discover it at startup and `GET /executors` shows it with a health check
27
+ (server reachable? aliases resolvable to models it actually has?).
28
+
29
+ Five-minute walkthrough with a local model: [`docs/quickstart-llm.md`](../../docs/quickstart-llm.md),
30
+ or `python scripts/quickstart_llm.py` against a running API.
31
+
32
+ ## Agent definition
33
+
34
+ ```json
35
+ {"name": "poet", "type": "llm", "executor": "openai-compat",
36
+ "config": {"model": "chat.fast",
37
+ "system": "You are a terse poet.",
38
+ "prompt": "Write a haiku about {run.topic}."}}
39
+ ```
40
+
41
+ | `config` key | meaning | default |
42
+ | --- | --- | --- |
43
+ | `model` | capability alias (`chat.fast`) or concrete id (`gpt-4o-mini`) | `chat.default` |
44
+ | `system` | system prompt | none |
45
+ | `prompt` | user-message template; `{run.x}` = run inputs, `{step.field}` = upstream output | inputs as JSON |
46
+ | `temperature` / `seed` | deterministic by default so cassettes replay | `0` / `42` |
47
+ | `max_tokens` | | server default |
48
+ | `json_output` | request a JSON object; parsed into `output.json` | `false` |
49
+
50
+ ## Environment
51
+
52
+ | variable | default | notes |
53
+ | --- | --- | --- |
54
+ | `AGENTOS_OPENAI_BASE_URL` | `http://127.0.0.1:11434/v1` | include `/v1` |
55
+ | `AGENTOS_OPENAI_API_KEY` | unset (falls back to `OPENAI_API_KEY`) | Ollama needs none |
56
+ | `AGENTOS_OPENAI_ALIASES` | `{"chat.fast": "qwen2.5:0.5b", "chat.default": "llama3.2:3b"}` | JSON, merged over the defaults |
57
+ | `AGENTOS_OPENAI_PRICING` | bundled `pricing.json` | content-addressed; hash on every step |
58
+ | `AGENTOS_OPENAI_TIMEOUT` | `60` | seconds |
59
+ | `AGENTOS_OPENAI_CASSETTES` | `off` | `replay` / `record` (tests) |
60
+ | `AGENTOS_OPENAI_CASSETTE_DIR` / `AGENTOS_OPENAI_CASSETTE` | `./cassettes` / `default` | |
61
+
62
+ A bad value raises `ConfigError` naming the variable; the API/worker log it and skip this
63
+ plugin rather than refusing to start.
64
+
65
+ ## What a step records
66
+
67
+ `output`: `text`, `model` (the id the server reports), `alias`, `finish_reason`, `usage`,
68
+ `priced`, and `json` when requested. `cost`: `input_tokens`, `output_tokens`, `requests`
69
+ meters, a Decimal `amount`, and `pricing_snapshot_hash` — the table's bytes are stored in
70
+ the BlobStore at startup (`GET /blobs/{hash}`). `provenance`: `openai-compat`, package
71
+ version, concrete `model_id`, `model_alias`, `prompt_hash`. Effects: `compute` only.
72
+
73
+ ## Aliases and substitution (§11 A3)
74
+
75
+ `resolve(req)` maps the alias to a concrete id without touching the network. If the
76
+ resolution for an agent changes *during* a run — alias re-pointed, model retired — the
77
+ engine appends `executor.substituted{from, to, reason}` before the next step. Completed
78
+ steps are never re-run.
79
+
80
+ ## Errors say what to do
81
+
82
+ | exception | when | message tells you |
83
+ | --- | --- | --- |
84
+ | `ProviderUnreachable` | connection refused | `ollama serve` / check `AGENTOS_OPENAI_BASE_URL` |
85
+ | `ModelNotFound` | 404 | `ollama pull <id>` or fix the alias |
86
+ | `AuthenticationFailed` | 401/403 | set `AGENTOS_OPENAI_API_KEY` |
87
+ | `ProviderRateLimited` / `ProviderServerError` | 429 / 5xx / timeout | the node's retry policy applies |
88
+ | `TemplateError` | `{x.y}` not in inputs | the keys that *are* available |
89
+ | `BadResponse` | malformed body or non-JSON when `json_output` | what came back |
90
+
91
+ The engine records each as `step.failed` → retries per the node's policy →
92
+ `step.dead_lettered` with the message as the cause.
93
+
94
+ ## Testing (§11 A10)
95
+
96
+ `tests/` runs against **cassettes recorded from a real Ollama** (`qwen2.5:0.5b`, see each
97
+ file's `source`), never the network. `tests/reference_server.py` fakes specific status
98
+ codes. Re-record: `python scripts/record_cassettes.py --live`. The nightly
99
+ [`provider-live`](../../.github/workflows/provider-live.yml) workflow installs Ollama on a
100
+ runner, re-records, and re-runs the replay tests on the fresh recordings. If that job fails
101
+ for 30 days this README gets a `deprecated` banner; the core is unaffected.
102
+
103
+ ## Status
104
+
105
+ `0.1.0` — first provider plugin. MIT.
@@ -0,0 +1,13 @@
1
+ README.md
2
+ pyproject.toml
3
+ agentos_provider_openai_compat/__init__.py
4
+ agentos_provider_openai_compat/config.py
5
+ agentos_provider_openai_compat/executor.py
6
+ agentos_provider_openai_compat/pricing.json
7
+ agentos_provider_openai_compat.egg-info/PKG-INFO
8
+ agentos_provider_openai_compat.egg-info/SOURCES.txt
9
+ agentos_provider_openai_compat.egg-info/dependency_links.txt
10
+ agentos_provider_openai_compat.egg-info/entry_points.txt
11
+ agentos_provider_openai_compat.egg-info/requires.txt
12
+ agentos_provider_openai_compat.egg-info/top_level.txt
13
+ tests/test_openai_compat.py
@@ -0,0 +1,2 @@
1
+ [agentos.executors]
2
+ openai-compat = agentos_provider_openai_compat:load
@@ -0,0 +1,6 @@
1
+ dagentos[providerkit]<1.0,>=0.11
2
+ httpx>=0.27
3
+
4
+ [dev]
5
+ pytest>=8.0
6
+ fastapi>=0.110
@@ -0,0 +1,32 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "agentos-provider-openai-compat"
7
+ version = "0.17.0"
8
+ description = "AgentOS executor for any OpenAI-compatible chat-completions server (Ollama, vLLM, LM Studio, OpenRouter, OpenAI) over plain HTTP"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = { text = "MIT" }
12
+ dependencies = [
13
+ "dagentos[providerkit]>=0.11,<1.0",
14
+ "httpx>=0.27",
15
+ ]
16
+
17
+ [project.urls]
18
+ Repository = "https://github.com/AmitSinghOM/AgentOS"
19
+
20
+ [project.optional-dependencies]
21
+ dev = ["pytest>=8.0", "fastapi>=0.110"] # fastapi only for the in-process reference server
22
+
23
+ # Discovered by `dagentos.plugins.discover_executors()` in the API and worker composition
24
+ # roots (docs/DEVELOPMENT_STRUCTURE.md §2.2). The core never imports this package.
25
+ [project.entry-points."agentos.executors"]
26
+ openai-compat = "agentos_provider_openai_compat:load"
27
+
28
+ [tool.setuptools]
29
+ packages = ["agentos_provider_openai_compat"]
30
+
31
+ [tool.setuptools.package-data]
32
+ agentos_provider_openai_compat = ["pricing.json"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,224 @@
1
+ """Provider tests run against recorded cassettes, never the network (§11 A10). The
2
+ in-process reference server (`openai_reference_server.py`) stands in for a live server where a
3
+ specific status code is needed."""
4
+ from __future__ import annotations
5
+
6
+ import json
7
+ import sys
8
+ from pathlib import Path
9
+
10
+ import httpx
11
+ import pytest
12
+
13
+ pytest.importorskip("agentos_provider_openai_compat")
14
+
15
+ from agentos_provider_openai_compat import (
16
+ AuthenticationFailed,
17
+ ConfigError,
18
+ ModelNotFound,
19
+ OpenAICompatExecutor,
20
+ ProviderRateLimited,
21
+ ProviderServerError,
22
+ ProviderUnreachable,
23
+ TemplateError,
24
+ from_env,
25
+ )
26
+
27
+ from dagentos.core.models import Agent, AgentType, BlobRef, Budget, StepRequest
28
+ from dagentos.providerkit.cassette import CassetteMiss
29
+ from dagentos.providerkit.pricing import PricingTable
30
+
31
+ HERE = Path(__file__).resolve().parent
32
+ sys.path.insert(0, str(HERE))
33
+ sys.path.insert(0, str(HERE.parent / "scripts"))
34
+ import openai_reference_server
35
+
36
+ from dagentos.providerkit.conformance import QUICKSTART, SCENARIOS, quickstart_requests, request_for
37
+
38
+ CASSETTES = HERE / "cassettes"
39
+
40
+
41
+ def replay(name: str, **over) -> OpenAICompatExecutor:
42
+ cfg = from_env({
43
+ "AGENTOS_OPENAI_BASE_URL": "http://reference-server/v1",
44
+ "AGENTOS_OPENAI_CASSETTES": "replay",
45
+ "AGENTOS_OPENAI_CASSETTE_DIR": str(CASSETTES), **over})
46
+ return OpenAICompatExecutor(cfg, cassette_name=name)
47
+
48
+
49
+ def scenario(name: str) -> StepRequest:
50
+ return request_for(name, *SCENARIOS[name])
51
+
52
+
53
+ def _progress(f, n):
54
+ pass
55
+
56
+
57
+ # ------------------------------------------------------------------ happy paths (replay)
58
+
59
+ def test_haiku_from_cassette_with_alias_pricing_and_provenance():
60
+ ex = replay(QUICKSTART)
61
+ notes: list[str] = []
62
+ res = ex.execute(quickstart_requests()[0], lambda f, n: notes.append(n))
63
+ assert res.output["text"].strip() # shape, not wording:
64
+ assert res.output["alias"] == "chat.fast" # the same test must
65
+ assert res.output["model"].startswith("qwen2.5:0.5b") # pass on a live
66
+ assert res.output["priced"] is True and res.cost.amount == "0" # re-recording (free)
67
+ meters = {m.name: m.quantity for m in res.cost.units}
68
+ assert set(meters) == {"input_tokens", "output_tokens", "requests"} and meters["requests"] == 1
69
+ assert meters["input_tokens"] > 0 and meters["output_tokens"] > 0
70
+ assert res.cost.pricing_snapshot_hash == ex.pricing.sha256
71
+ p = res.provenance
72
+ assert (p.executor, p.model_alias) == ("openai-compat", "chat.fast")
73
+ assert p.model_id == res.output["model"] and len(p.prompt_hash) == 64
74
+ assert [e.effect_class.value for e in res.effects] == ["compute"]
75
+ assert notes[0].startswith("POST ") and notes[0].endswith("model=qwen2.5:0.5b")
76
+ assert notes[-1].endswith("tokens, 0 USD")
77
+
78
+
79
+ def test_json_output_is_parsed():
80
+ ex = replay(QUICKSTART)
81
+ poet = ex.execute(quickstart_requests()[0], _progress)
82
+ res = ex.execute(quickstart_requests(poet.output["text"])[1], _progress)
83
+ j = res.output["json"]
84
+ assert isinstance(j, dict) and isinstance(j.get("score"), int | float)
85
+ assert isinstance(j.get("reason"), str) and j["reason"].strip()
86
+
87
+
88
+ def test_inputs_without_template_are_sent_as_json():
89
+ res = replay("plain").execute(scenario("plain"), _progress)
90
+ assert res.output["text"].strip()
91
+ assert res.output["alias"] == "chat.fast" # shared scenario
92
+
93
+
94
+ def test_replay_never_touches_the_network():
95
+ class Boom(httpx.BaseTransport):
96
+ def handle_request(self, request):
97
+ raise AssertionError("network used during replay")
98
+
99
+ ex = OpenAICompatExecutor(replay(QUICKSTART).config, transport=Boom(), cassette_name=QUICKSTART)
100
+ assert ex.execute(quickstart_requests()[0], _progress).output["model"] == "qwen2.5:0.5b"
101
+
102
+
103
+ def test_cassettes_are_labelled_with_their_source():
104
+ for f in CASSETTES.glob("*.json"):
105
+ data = json.loads(f.read_text())
106
+ assert data["format"] == "agentos.cassette/1" and data["source"] and data["recorded_at"]
107
+ for i in data["interactions"]:
108
+ assert "authorization" not in {k.lower() for k in i["request"]["headers"]}
109
+
110
+
111
+ # ------------------------------------------------------------------ errors that explain
112
+
113
+ def test_missing_model_error_says_how_to_pull_it():
114
+ with pytest.raises(ModelNotFound) as e:
115
+ replay("missing_model").execute(scenario("missing_model"), _progress)
116
+ msg = str(e.value)
117
+ assert "ollama pull no-such-model:1b" in msg and "AGENTOS_OPENAI_ALIASES" in msg
118
+ assert "Server said:" in msg # server's own words
119
+
120
+
121
+ def test_cassette_miss_tells_you_to_re_record():
122
+ ex = replay(QUICKSTART)
123
+ req = quickstart_requests()[0].model_copy(update={"inputs": {"run": {"topic": "something else"}}})
124
+ with pytest.raises(CassetteMiss, match="AGENTOS_OPENAI_CASSETTES=record"):
125
+ ex.execute(req, _progress)
126
+
127
+
128
+ def test_unreachable_default_ollama_gives_the_start_hint():
129
+ def down(request):
130
+ raise httpx.ConnectError("connection refused", request=request)
131
+
132
+ ex = OpenAICompatExecutor(from_env({}), transport=httpx.MockTransport(down))
133
+ with pytest.raises(ProviderUnreachable) as e:
134
+ ex.execute(scenario("plain"), _progress)
135
+ assert "127.0.0.1:11434" in str(e.value) and "ollama serve" in str(e.value)
136
+ assert ex.health()["reachable"] is False and "ollama serve" in ex.health()["hint"]
137
+
138
+
139
+ def test_auth_failure_names_the_variable_and_key_fixes_it():
140
+ t = openai_reference_server.transport(require_key=True)
141
+ cfg = from_env({"AGENTOS_OPENAI_BASE_URL": "http://reference-server/v1"})
142
+ with pytest.raises(AuthenticationFailed, match="AGENTOS_OPENAI_API_KEY.*unset"):
143
+ OpenAICompatExecutor(cfg, transport=t).execute(scenario("plain"), _progress)
144
+ cfg = from_env({"AGENTOS_OPENAI_BASE_URL": "http://reference-server/v1",
145
+ "OPENAI_API_KEY": openai_reference_server.API_KEY})
146
+ assert OpenAICompatExecutor(cfg, transport=t).execute(scenario("plain"), _progress).output
147
+
148
+
149
+ @pytest.mark.parametrize("status,exc", [(429, ProviderRateLimited), (500, ProviderServerError),
150
+ (503, ProviderServerError)])
151
+ def test_transient_server_errors_say_retry_policy_applies(status, exc):
152
+ cfg = from_env({"AGENTOS_OPENAI_BASE_URL": "http://reference-server/v1"})
153
+ ex = OpenAICompatExecutor(cfg, transport=openai_reference_server.transport(fail_with=status))
154
+ with pytest.raises(exc, match="retry policy applies"):
155
+ ex.execute(scenario("plain"), _progress)
156
+
157
+
158
+ def test_template_error_lists_available_keys():
159
+ cfg = from_env({"AGENTOS_OPENAI_BASE_URL": "http://reference-server/v1"})
160
+ ex = OpenAICompatExecutor(cfg, transport=openai_reference_server.transport())
161
+ req = request_for("t", {"prompt": "Summarise {draft.text}"}, {"run": {"topic": "x"}})
162
+ with pytest.raises(TemplateError, match=r"\{draft.text\}.*available top-level keys: \['run'\]"):
163
+ ex.execute(req, _progress)
164
+
165
+
166
+ # ------------------------------------------------------------------ config, pricing, hooks
167
+
168
+ def test_config_env_overrides_and_errors():
169
+ cfg = from_env({"AGENTOS_OPENAI_ALIASES": '{"chat.fast": "gpt-4o-mini"}',
170
+ "AGENTOS_OPENAI_BASE_URL": "https://api.openai.com/v1/"})
171
+ assert cfg.resolve("chat.fast") == ("gpt-4o-mini", "chat.fast")
172
+ assert cfg.resolve("chat.default") == ("llama3.2:3b", "chat.default") # defaults kept
173
+ assert cfg.resolve("gpt-4.1") == ("gpt-4.1", None)
174
+ assert cfg.base_url == "https://api.openai.com/v1"
175
+ with pytest.raises(ConfigError, match="AGENTOS_OPENAI_ALIASES is not valid JSON"):
176
+ from_env({"AGENTOS_OPENAI_ALIASES": "{oops"})
177
+ with pytest.raises(ConfigError, match="off \\| replay \\| record"):
178
+ from_env({"AGENTOS_OPENAI_CASSETTES": "maybe"})
179
+ with pytest.raises(ConfigError, match="does not exist"):
180
+ from_env({"AGENTOS_OPENAI_PRICING": "/nope/pricing.json"})
181
+
182
+
183
+ def test_pricing_is_decimal_and_content_addressed():
184
+ table = PricingTable(from_env({}).pricing_path)
185
+ cost, priced = table.cost("gpt-4o-mini", 1000, 500)
186
+ assert priced and cost.amount == "0.00045" and cost.currency == "USD"
187
+ cost, priced = table.cost("gpt-4o-mini-2024-07-18", 1_000_000, 0) # dated variant
188
+ assert priced and cost.amount == "0.15"
189
+ cost, priced = table.cost("mystery-9b", 10, 10)
190
+ assert not priced and cost.amount == "0" and len(cost.units) == 3
191
+ assert cost.pricing_snapshot_hash == table.sha256 == __import__("hashlib").sha256(
192
+ table.snapshot()).hexdigest()
193
+
194
+
195
+ def test_resolve_describe_and_health_hooks():
196
+ cfg = from_env({"AGENTOS_OPENAI_BASE_URL": "http://reference-server/v1"})
197
+ ex = OpenAICompatExecutor(cfg, transport=openai_reference_server.transport())
198
+ assert ex.resolve(quickstart_requests()[0]) == "qwen2.5:0.5b"
199
+ d = ex.describe()
200
+ assert d["aliases"]["chat.fast"] == "qwen2.5:0.5b" and d["pricing"]["sha256"] == ex.pricing.sha256
201
+ h = ex.health()
202
+ assert h["reachable"] and "qwen2.5:0.5b" in h["models"]
203
+ assert h["aliases_available"] == {"chat.fast": True, "chat.default": True}
204
+ assert ex.pricing_snapshot() == ex.pricing.snapshot()
205
+
206
+
207
+ def test_record_then_replay_round_trip(tmp_path):
208
+ env = {"AGENTOS_OPENAI_BASE_URL": "http://reference-server/v1",
209
+ "AGENTOS_OPENAI_CASSETTE_DIR": str(tmp_path)}
210
+ rec = OpenAICompatExecutor(from_env({**env, "AGENTOS_OPENAI_CASSETTES": "record"}),
211
+ transport=openai_reference_server.transport(), cassette_name="rt")
212
+ first = rec.execute(quickstart_requests()[0], _progress)
213
+ assert (tmp_path / "rt.json").exists()
214
+ rep = OpenAICompatExecutor(from_env({**env, "AGENTOS_OPENAI_CASSETTES": "replay"}),
215
+ cassette_name="rt")
216
+ second = rep.execute(quickstart_requests()[0], _progress)
217
+ assert first.output == second.output and first.provenance == second.provenance
218
+
219
+
220
+ def test_agent_definition_round_trips_through_core_models():
221
+ a = Agent(name="writer", type=AgentType.llm, executor="openai-compat",
222
+ config={"model": "chat.fast", "prompt": "x {run.topic}"})
223
+ assert Agent.model_validate_json(a.model_dump_json()) == a
224
+ assert Budget().max_run_cost is None and BlobRef(sha256="0" * 64, size=0).size == 0