voxora-ai-runtime 0.1.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,10 @@
1
+ Metadata-Version: 2.4
2
+ Name: voxora-ai-runtime
3
+ Version: 0.1.0
4
+ Summary: Deterministic mock AI agent runtime contract for Voxora Studio
5
+ Requires-Python: >=3.9
6
+ Requires-Dist: httpx>=0.27.2
7
+ Requires-Dist: typing-extensions>=4.12.2
8
+ Provides-Extra: dev
9
+ Requires-Dist: pytest<9,>=8; extra == "dev"
10
+ Requires-Dist: httpx>=0.27.2; extra == "dev"
@@ -0,0 +1,28 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "voxora-ai-runtime"
7
+ version = "0.1.0"
8
+ description = "Deterministic mock AI agent runtime contract for Voxora Studio"
9
+ requires-python = ">=3.9"
10
+ dependencies = ["httpx>=0.27.2", "typing-extensions>=4.12.2"]
11
+
12
+ [project.optional-dependencies]
13
+ dev = ["pytest>=8,<9", "httpx>=0.27.2"]
14
+
15
+ [tool.setuptools.packages.find]
16
+ where = ["src"]
17
+
18
+ [tool.ruff]
19
+ line-length = 100
20
+ target-version = "py39"
21
+
22
+ [tool.ruff.lint]
23
+ select = ["E", "F", "I", "UP", "B", "SIM"]
24
+ ignore = ["UP006", "UP007", "UP035", "UP045", "UP037", "B008", "E501"]
25
+
26
+ [tool.pytest.ini_options]
27
+ pythonpath = ["src"]
28
+ testpaths = ["tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,23 @@
1
+ """Voxora AI runtime: deterministic mock agent backend.
2
+
3
+ Honest scope: this package implements the *contract* the orchestrator will
4
+ use for agent reasoning (one deterministic reply method, explicit
5
+ capabilities) and a fully working mock implementation. No real LLM client is
6
+ implemented; ``capabilities`` lists what is actually implemented.
7
+ """
8
+
9
+ from .engine import AgentBrain, AgentReply, AgentTurnError, MockAgent
10
+ from .openrouter import OpenRouterAgent, OpenRouterError, create_agent_from_env
11
+
12
+ __all__ = [
13
+ "AgentBrain",
14
+ "AgentReply",
15
+ "AgentTurnError",
16
+ "MockAgent",
17
+ "OpenRouterAgent",
18
+ "OpenRouterError",
19
+ "__version__",
20
+ "create_agent_from_env",
21
+ ]
22
+
23
+ __version__ = "0.1.0"
@@ -0,0 +1,109 @@
1
+ """Deterministic script-driven agent backend for simulated calls.
2
+
3
+ The orchestrator's calls are simulated; the mock agent produces replies with
4
+ a hash-derived pseudo-render latency so behavior is reproducible in tests,
5
+ and it declares its capabilities honestly (no real LLM, no VAD, no audio).
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import hashlib
11
+ from dataclasses import dataclass, field
12
+ from typing import Dict, List, Optional, Protocol, runtime_checkable
13
+
14
+ _END_KEYWORDS = ("goodbye", "bye", "stop calling", "end call")
15
+ _CLOSING = "Understood. Ending the simulated call now. Goodbye."
16
+
17
+
18
+ class AgentTurnError(Exception):
19
+ """The backend was used incorrectly (out-of-order calls)."""
20
+
21
+
22
+ @runtime_checkable
23
+ class AgentBrain(Protocol):
24
+ """Optional conversation-policy hook, for downstream products.
25
+
26
+ Voxora owns the call lifecycle and (when configured) the model call; a
27
+ brain may take over per-turn wording or end-call decisions. Returning
28
+ ``None`` hands the turn back to Voxora's default phrasing. Implementing
29
+ this does not create any Voxora dependency in the brain."""
30
+
31
+ def respond(self, user_text: str, history: List[Dict[str, str]]) -> Optional["AgentReply"]:
32
+ """Return the next agent turn, or ``None`` to defer to the engine."""
33
+ ...
34
+
35
+
36
+ def turn_from_reply(reply: Optional[AgentReply], fallback_reply: AgentReply) -> AgentReply:
37
+ """Prefer the brain's turn (including its explicit end_call), else the engine's."""
38
+ if reply is None or (not reply.text.strip() and not reply.ended):
39
+ return fallback_reply
40
+ return reply
41
+
42
+
43
+ @dataclass(frozen=True)
44
+ class AgentReply:
45
+ """One agent turn."""
46
+
47
+ text: str
48
+ ended: bool = False
49
+ turn_index: int = 1
50
+
51
+ @property
52
+ def latency_simulated_ms(self) -> float:
53
+ digest = hashlib.sha256(self.text.encode("utf-8")).digest()
54
+ return 120.0 + digest[0] % 330
55
+
56
+
57
+ @dataclass
58
+ class MockAgent:
59
+ """Deterministic script-driven agent.
60
+
61
+ The script maps turn index -> reply text; anything past the script falls
62
+ back to a closing reply marked ``ended``. A user "goodbye"/"end call"
63
+ closes the call immediately.
64
+ """
65
+
66
+ name: str = "Simulated outbound agent"
67
+ script: List[str] = field(
68
+ default_factory=lambda: [
69
+ "Hello, this is a simulated call from Voxora Studio. Am I reaching you?",
70
+ "Thanks for confirming. This call is a simulation; nothing is live.",
71
+ "Understood. Ending the simulated call now. Goodbye.",
72
+ ]
73
+ )
74
+ capabilities: Dict[str, bool] = field(
75
+ default_factory=lambda: {
76
+ "real_llm": False,
77
+ "audio_mixing": False,
78
+ "barge_in_vad": False,
79
+ "scripted": True,
80
+ }
81
+ )
82
+
83
+ _turn: int = 0
84
+ _started: bool = False
85
+
86
+ def start(self) -> AgentReply:
87
+ self._turn = 0
88
+ self._started = True
89
+ return self._reply()
90
+
91
+ def respond(self, user_text: str) -> AgentReply:
92
+ if not self._started:
93
+ raise AgentTurnError("call has not been started; call start() first")
94
+ self._turn += 1
95
+ lowered = user_text.strip().lower()
96
+ if any(keyword in lowered for keyword in _END_KEYWORDS):
97
+ self._started = False
98
+ return AgentReply(_CLOSING, ended=True, turn_index=self._turn + 1)
99
+ return self._reply()
100
+
101
+ def _reply(self) -> AgentReply:
102
+ index = self._turn
103
+ if index >= len(self.script):
104
+ return AgentReply(_CLOSING, ended=True, turn_index=index + 1)
105
+ return AgentReply(
106
+ self.script[index],
107
+ ended=index == len(self.script) - 1,
108
+ turn_index=index + 1,
109
+ )
@@ -0,0 +1,490 @@
1
+ """OpenRouter OpenAI-compatible language-model agent provider.
2
+
3
+ Ported from PyInterviewBot's verified implementation and adapted to Voxora's
4
+ synchronous agent contract (`start()` / `respond()` -> `AgentReply`).
5
+
6
+ Model selection is explicit (`OPENROUTER_MODEL`); API keys stay server-side
7
+ and are never logged or returned. OpenRouter bills per-token against the key
8
+ owner's OpenRouter account. To make that billing visible to the operator we
9
+ request `usage.include = true`; OpenRouter then reports `cost` (USD, as a
10
+ string) on the response, which we accumulate in `usage_report()`. No cost
11
+ reader is hidden or simulated — when the field is absent we record zeros and
12
+ say so.
13
+
14
+ Provider selection is explicit and fail-closed via `VOXORA_LLM_PROVIDER`
15
+ (`mock` default, `openrouter` opt-in); see `create_agent_from_env`.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import json
21
+ import os
22
+ import threading
23
+ from typing import Any, Dict, List, Optional
24
+
25
+ try: # httpx is optional at import so `mock` keeps working without it
26
+ import httpx # type: ignore[import-not-found]
27
+ except ImportError: # pragma: no cover - httpx is a declared project dependency
28
+ httpx = None
29
+
30
+ from .engine import AgentBrain, AgentReply, AgentTurnError, MockAgent
31
+
32
+ DEFAULT_BASE_URL = "https://openrouter.ai/api/v1"
33
+
34
+ _END_KEYWORDS = ("goodbye", "bye", "stop calling", "end call")
35
+
36
+ # Statuses worth retrying: timeout/conflict/rate-limit + upstream server errors.
37
+ _RETRYABLE_STATUS = frozenset({408, 409, 429, 500, 502, 503, 504})
38
+
39
+
40
+ class OpenRouterError(RuntimeError):
41
+ def __init__(
42
+ self,
43
+ message: str,
44
+ status_code: Optional[int] = None,
45
+ retryable: bool = False,
46
+ ):
47
+ super().__init__(message)
48
+ self.status_code = status_code
49
+ self.retryable = retryable
50
+
51
+
52
+ def _safe_float(value: Optional[str]) -> Optional[float]:
53
+ if value is None:
54
+ return None
55
+ try:
56
+ return float(value)
57
+ except ValueError:
58
+ return None
59
+
60
+
61
+ def _env_int(name: str, default: int) -> int:
62
+ try:
63
+ return int(os.environ.get(name, str(default)))
64
+ except ValueError:
65
+ return default
66
+
67
+
68
+ def _strip_json(content: str) -> str:
69
+ text = content.strip()
70
+ if text.startswith("```"):
71
+ lines = text.splitlines()
72
+ if lines and lines[0].startswith("```"):
73
+ lines = lines[1:]
74
+ if lines and lines[-1].strip() == "```":
75
+ lines = lines[:-1]
76
+ text = "\n".join(lines).strip()
77
+ return text
78
+
79
+
80
+ def _parse_reply(content: str, turn_index: int) -> "AgentReply":
81
+ """Parse model output as {"text": ..., "end_call": bool}.
82
+
83
+ Non-JSON output raises so the caller can retry with a corrective
84
+ instruction; the caller falls back to the raw text only after retries
85
+ are exhausted.
86
+ """
87
+ data: Any
88
+ if isinstance(content, dict): # defensive
89
+ data = content
90
+ else:
91
+ try:
92
+ data = json.loads(_strip_json(str(content)))
93
+ except (json.JSONDecodeError, TypeError) as error:
94
+ raise ValueError(f"model returned non-JSON output: {str(content)[:80]!r}") from error
95
+ if not isinstance(data, dict):
96
+ raise ValueError("model JSON output is not an object")
97
+ text = str(data.get("text") or data.get("message") or "").strip()
98
+ ended = bool(data.get("end_call", data.get("is_complete", False)))
99
+ return AgentReply(text=text or "(no reply)", ended=ended, turn_index=turn_index)
100
+
101
+
102
+ class OpenRouterAgent:
103
+ """LLM agent over OpenRouter's OpenAI-compatible chat completions.
104
+
105
+ Mirrors `MockAgent`'s surface: `start()` and `respond(user_text)` return
106
+ the same `AgentReply` shape, and the same end-keywords close the call
107
+ locally (belt and suspenders — the model is also allowed to set
108
+ `"end_call": true`). Capabilities declare real_llm honestly.
109
+ """
110
+
111
+ provider = "openrouter"
112
+
113
+ def __init__(
114
+ self,
115
+ *,
116
+ api_key: Optional[str] = None,
117
+ model: Optional[str] = None,
118
+ system_prompt: Optional[str] = None,
119
+ base_url: Optional[str] = None,
120
+ timeout: Optional[float] = None,
121
+ max_retries: Optional[int] = None,
122
+ retry_base_delay: float = 0.25,
123
+ site_url: Optional[str] = None,
124
+ app_name: Optional[str] = None,
125
+ response_format: Optional[str] = None,
126
+ client: Any = None,
127
+ brain: Optional[AgentBrain] = None,
128
+ ) -> None:
129
+ if httpx is None:
130
+ raise OpenRouterError("httpx is required for the openrouter provider")
131
+ self.api_key = api_key or os.environ.get("OPENROUTER_API_KEY")
132
+ self.model = model or os.environ.get("OPENROUTER_MODEL")
133
+ if not self.api_key:
134
+ raise ValueError("OPENROUTER_API_KEY is required for the openrouter provider")
135
+ if not self.model:
136
+ raise ValueError(
137
+ "OPENROUTER_MODEL is required; set it to the exact OpenRouter model id"
138
+ )
139
+ self.base_url = (
140
+ base_url or os.environ.get("OPENROUTER_BASE_URL", DEFAULT_BASE_URL)
141
+ ).rstrip("/")
142
+ self.timeout = timeout if timeout is not None else float(os.environ.get("OPENROUTER_TIMEOUT_SECONDS", "60"))
143
+ self.max_retries = max_retries if max_retries is not None else _env_int("OPENROUTER_MAX_RETRIES", 1)
144
+ self.retry_base_delay = retry_base_delay
145
+ self.system_prompt = system_prompt or os.environ.get(
146
+ "OPENROUTER_SYSTEM_PROMPT",
147
+ "You are the outbound AI voice agent for Voxora Studio. Reply with a short spoken line."
148
+ ' Respond with JSON {"text": string, "end_call": boolean}.',
149
+ )
150
+ self._response_format = (
151
+ response_format
152
+ if response_format is not None
153
+ else os.environ.get("OPENROUTER_RESPONSE_FORMAT", "json_object")
154
+ )
155
+ self._site_url = site_url or os.environ.get("OPENROUTER_SITE_URL")
156
+ self._app_name = app_name or os.environ.get("OPENROUTER_APP_NAME")
157
+ self._client = client or httpx.Client(base_url=self.base_url, timeout=self.timeout)
158
+ self.brain = brain
159
+
160
+ self.capabilities: Dict[str, bool] = {
161
+ "real_llm": True,
162
+ "audio_mixing": False,
163
+ "barge_in_vad": False,
164
+ "scripted": False,
165
+ }
166
+ self._started = False
167
+ self._turn = 0
168
+ self._history: List[Dict[str, str]] = []
169
+ self._lock = threading.Lock()
170
+ self.last_usage: Dict[str, float] = {}
171
+ self._totals: Dict[str, float] = {"prompt_tokens": 0.0, "completion_tokens": 0.0, "total_tokens": 0.0, "cost_usd": 0.0}
172
+
173
+ # ---------------------------------------------------------------- config
174
+ def _headers(self) -> Dict[str, str]:
175
+ headers = {"Authorization": f"Bearer {self.api_key}"}
176
+ if self._site_url:
177
+ headers["HTTP-Referer"] = self._site_url
178
+ if self._app_name:
179
+ headers["X-Title"] = self._app_name
180
+ return headers
181
+
182
+ def usage_report(self) -> Dict[str, float]:
183
+ """Accumulated billing data as reported by OpenRouter (`usage.include`)."""
184
+ return dict(self._totals)
185
+
186
+ # ------------------------------------------------------------------ flow
187
+ def start(self) -> AgentReply:
188
+ self._started = True
189
+ self._turn = 0
190
+ self._history = []
191
+ return self._decide("The call just connected. Say your opening line.")
192
+
193
+ def respond(self, user_text: str) -> AgentReply:
194
+ if not self._started:
195
+ raise AgentTurnError("call has not been started; call start() first")
196
+ lowered = str(user_text).strip().lower()
197
+ self._turn += 1
198
+ if any(keyword in lowered for keyword in _END_KEYWORDS):
199
+ self._started = False
200
+ return AgentReply("Understood. Ending the call now. Goodbye.", ended=True, turn_index=self._turn + 1)
201
+ self._history.append({"role": "user", "content": str(user_text)})
202
+ brain_turn = None
203
+ if self.brain is not None:
204
+ brain_turn = self.brain.respond(user_text, list(self._history))
205
+ if brain_turn is not None and (brain_turn.text.strip() or brain_turn.ended):
206
+ reply = brain_turn
207
+ else:
208
+ reply = self._decide(f"The contact just said: {user_text!r}")
209
+ if reply.ended:
210
+ self._started = False
211
+ return reply
212
+
213
+ # ------------------------------------------------------------------- LLM
214
+ def _decide(self, user_prompt: str) -> AgentReply:
215
+ messages = [{"role": "system", "content": self.system_prompt}, *self._history[-10:]]
216
+ messages.append({"role": "user", "content": user_prompt})
217
+ include_format = bool(self._response_format and self._response_format != "none")
218
+ format_fallback_used = False
219
+ last_error = "OpenRouter request failed"
220
+ for attempt in range(self.max_retries + 1):
221
+ payload: Dict[str, Any] = {
222
+ "model": self.model,
223
+ "messages": messages,
224
+ "temperature": 0.4,
225
+ "usage": {"include": True},
226
+ }
227
+ if include_format:
228
+ payload["response_format"] = {"type": self._response_format}
229
+ try:
230
+ response = self._client.post(
231
+ "/chat/completions",
232
+ headers=self._headers(),
233
+ json=payload,
234
+ timeout=self.timeout,
235
+ )
236
+ except Exception as error: # noqa: BLE001 - transport errors are retryable
237
+ last_error = str(error)
238
+ if attempt < self.max_retries:
239
+ import time
240
+
241
+ time.sleep(self.retry_base_delay * (2**attempt))
242
+ continue
243
+ raise OpenRouterError(f"transport failure: {last_error}", retryable=True) from error
244
+
245
+ status = response.status_code
246
+ if status in {400, 422} and include_format and not format_fallback_used:
247
+ include_format = False
248
+ format_fallback_used = True
249
+ continue
250
+ if status >= 400:
251
+ retryable = status in {408, 409, 429} or status >= 500
252
+ detail = response.text[:300] if response.text else ""
253
+ last_error = f"HTTP {status}: {detail}"
254
+ if retryable and attempt < self.max_retries:
255
+ import time
256
+
257
+ time.sleep(self.retry_base_delay * (2**attempt))
258
+ continue
259
+ raise OpenRouterError(last_error, status_code=status, retryable=retryable)
260
+
261
+ try:
262
+ body = response.json()
263
+ message = body["choices"][0]["message"]["content"]
264
+ usage = body.get("usage") or {}
265
+ self._record_usage(usage)
266
+ reply = _parse_reply(message if message is not None else "", self._turn + 1)
267
+ except (KeyError, IndexError, TypeError, ValueError) as error:
268
+ last_error = f"invalid model response: {error}"
269
+ if attempt < self.max_retries:
270
+ messages = [*messages, {"role": "user", "content": "Return only the requested JSON object, with no markdown."}]
271
+ continue
272
+ raw_text = (message if isinstance(message, str) else "").strip()
273
+ if raw_text:
274
+ reply = AgentReply(text=raw_text, ended=False, turn_index=self._turn + 1)
275
+ else:
276
+ raise OpenRouterError(last_error, retryable=False) from error
277
+ self._history.append({"role": "assistant", "content": reply.text})
278
+ return reply
279
+ raise OpenRouterError(last_error, retryable=False)
280
+
281
+ def _record_usage(self, usage: Dict[str, Any]) -> None:
282
+ prompt = float(usage.get("prompt_tokens", 0) or 0)
283
+ completion = float(usage.get("completion_tokens", 0) or 0)
284
+ total = float(usage.get("total_tokens", prompt + completion) or prompt + completion)
285
+ cost = usage.get("cost")
286
+ cost_value = 0.0
287
+ if cost is not None:
288
+ try:
289
+ cost_value = float(cost) # OpenRouter reports cost as a USD string
290
+ except (TypeError, ValueError):
291
+ cost_value = 0.0
292
+ self.last_usage = {
293
+ "prompt_tokens": prompt,
294
+ "completion_tokens": completion,
295
+ "total_tokens": total,
296
+ "cost_usd": cost_value,
297
+ }
298
+ with self._lock:
299
+ self._totals["prompt_tokens"] += prompt
300
+ self._totals["completion_tokens"] += completion
301
+ self._totals["total_tokens"] += total
302
+ self._totals["cost_usd"] += cost_value
303
+
304
+ # --------------------------------------------------------------- health
305
+ def health(self) -> bool:
306
+ """Reachable + authorized (OpenRouter key works for /models)."""
307
+ try:
308
+ response = self._client.get(
309
+ "/models", headers=self._headers(), timeout=min(self.timeout, 10.0)
310
+ )
311
+ except Exception: # noqa: BLE001 - network failure is unavailability
312
+ return False
313
+ return response.status_code < 400
314
+
315
+ def status(self) -> Dict[str, Any]:
316
+ return {
317
+ "provider": self.provider,
318
+ "model": self.model,
319
+ "capabilities": self.capabilities,
320
+ "usage": self.usage_report(),
321
+ }
322
+
323
+
324
+ def create_agent_from_env(env: Optional[Dict[str, str]] = None) -> Any:
325
+ """Build the configured agent: VOXORA_LLM_PROVIDER = mock | openrouter."""
326
+ source = env or os.environ
327
+ selection = (source.get("VOXORA_LLM_PROVIDER") or "mock").strip().lower()
328
+ if selection == "mock":
329
+ return MockAgent()
330
+ if selection == "openrouter":
331
+ return OpenRouterAgent(
332
+ api_key=source.get("OPENROUTER_API_KEY"),
333
+ model=source.get("OPENROUTER_MODEL"),
334
+ timeout=_safe_float(source.get("VOXORA_OPENROUTER_TIMEOUT")),
335
+ system_prompt=source.get("OPENROUTER_SYSTEM_PROMPT"),
336
+ )
337
+ raise ValueError(
338
+ f"Unknown VOXORA_LLM_PROVIDER '{selection}'; expected 'mock' or 'openrouter'"
339
+ )
340
+
341
+
342
+ class OpenRouterLLM:
343
+ """Stateless model-decision router (no conversation lifecycle).
344
+
345
+ Used by the '/api/v1/ai/decide' endpoint: downstream applications keep
346
+ their interview/methodology logic; Voxora hosts the key, chooses the
347
+ model, and records usage honestly. Same retryable map and billing
348
+ capture as OpenRouterAgent.
349
+ """
350
+
351
+ provider = "openrouter"
352
+
353
+ def __init__(
354
+ self,
355
+ *,
356
+ api_key: Optional[str] = None,
357
+ model: Optional[str] = None,
358
+ base_url: Optional[str] = None,
359
+ timeout: Optional[float] = None,
360
+ max_retries: Optional[int] = None,
361
+ retry_base_delay: float = 0.25,
362
+ site_url: Optional[str] = None,
363
+ app_name: Optional[str] = None,
364
+ client: Any = None,
365
+ ) -> None:
366
+ if httpx is None:
367
+ raise OpenRouterError("httpx is required for the openrouter provider")
368
+ self.api_key = api_key or os.environ.get("OPENROUTER_API_KEY")
369
+ self.model = model or os.environ.get("OPENROUTER_MODEL")
370
+ if not self.api_key:
371
+ raise ValueError("OPENROUTER_API_KEY is required for the openrouter provider")
372
+ if not self.model:
373
+ raise ValueError("OPENROUTER_MODEL is required; set the exact OpenRouter model id")
374
+ self.base_url = (
375
+ base_url or os.environ.get("OPENROUTER_BASE_URL", DEFAULT_BASE_URL)
376
+ ).rstrip("/")
377
+ self.timeout = timeout if timeout is not None else float(
378
+ os.environ.get("OPENROUTER_TIMEOUT_SECONDS", "60")
379
+ )
380
+ self.max_retries = max_retries if max_retries is not None else _env_int(
381
+ "OPENROUTER_MAX_RETRIES", 1
382
+ )
383
+ self.retry_base_delay = retry_base_delay
384
+ self._site_url = site_url or os.environ.get("OPENROUTER_SITE_URL")
385
+ self._app_name = app_name or os.environ.get("OPENROUTER_APP_NAME", "Voxora Studio")
386
+ # Synchronous client by default: Voxora's agent contract (`start()` /
387
+ # `respond()` / `decide()`) is synchronous, so an AsyncClient here
388
+ # would return unawaited coroutines and crash every call. Inject a
389
+ # custom client for tests or exotic transports.
390
+ self._client = client if client is not None else httpx.Client(
391
+ base_url=self.base_url, timeout=self.timeout
392
+ )
393
+ self._tokens = {"prompt": 0, "completion": 0, "total": 0}
394
+ self._cost_usd = 0.0
395
+ self._lock = threading.Lock()
396
+
397
+ def usage_report(self) -> Dict[str, float]:
398
+ with self._lock:
399
+ return {
400
+ "prompt_tokens": float(self._tokens["prompt"]),
401
+ "completion_tokens": float(self._tokens["completion"]),
402
+ "total_tokens": float(self._tokens["total"]),
403
+ "cost_usd": self._cost_usd,
404
+ }
405
+
406
+ def _record_usage(self, usage: Dict[str, Any]) -> None:
407
+ with self._lock:
408
+ self._tokens["prompt"] += int(usage.get("prompt_tokens") or 0)
409
+ self._tokens["completion"] += int(usage.get("completion_tokens") or 0)
410
+ self._tokens["total"] += int(usage.get("total_tokens") or 0)
411
+ try:
412
+ cost = usage.get("cost")
413
+ self._cost_usd += float(cost) if cost is not None else 0.0
414
+ except (TypeError, ValueError):
415
+ pass
416
+
417
+ def decide(
418
+ self,
419
+ system_prompt: str,
420
+ user_prompt: str,
421
+ *,
422
+ response_format: str = "json_object",
423
+ temperature: Optional[float] = None,
424
+ ) -> Dict[str, Any]:
425
+ """One-shot decision: returns the parsed JSON object the model produced."""
426
+ import time
427
+
428
+ payload: Dict[str, Any] = {
429
+ "model": self.model,
430
+ "messages": [
431
+ {"role": "system", "content": system_prompt},
432
+ {"role": "user", "content": user_prompt},
433
+ ],
434
+ "usage": {"include": True},
435
+ }
436
+ if temperature is not None:
437
+ payload["temperature"] = temperature
438
+ if response_format == "json_object":
439
+ payload["response_format"] = {"type": "json_object"}
440
+ headers: Dict[str, str] = {"Authorization": f"Bearer {self.api_key}"}
441
+ if self._app_name:
442
+ headers["X-Title"] = self._app_name
443
+ if self._site_url:
444
+ headers["HTTP-Referer"] = self._site_url
445
+ last_error = "OpenRouter request failed"
446
+ for attempt in range(self.max_retries + 1):
447
+ try:
448
+ response = self._client.post("/chat/completions", json=payload, headers=headers)
449
+ except Exception as error:
450
+ last_error = f"transport_failure: {type(error).__name__}: {error}"[:300]
451
+ if attempt < self.max_retries:
452
+ time.sleep(self.retry_base_delay * (2**attempt))
453
+ continue
454
+ raise OpenRouterError(last_error, retryable=True) from error
455
+ if response.status_code in _RETRYABLE_STATUS:
456
+ retry_after = response.headers.get("retry-after")
457
+ try:
458
+ wait = float(retry_after) if retry_after else None
459
+ except (TypeError, ValueError):
460
+ wait = None
461
+ if attempt < self.max_retries:
462
+ time.sleep(wait or (self.retry_base_delay * (2**attempt)))
463
+ continue
464
+ raise OpenRouterError(
465
+ f"openrouter_http_{response.status_code}", retryable=True
466
+ )
467
+ if response.status_code != 200:
468
+ raise OpenRouterError(
469
+ f"openrouter_http_{response.status_code}",
470
+ retryable=response.status_code in _RETRYABLE_STATUS,
471
+ )
472
+ try:
473
+ body = response.json()
474
+ message = body["choices"][0]["message"]["content"]
475
+ self._record_usage(body.get("usage") or {})
476
+ except (KeyError, IndexError, TypeError) as error:
477
+ raise OpenRouterError(
478
+ f"invalid model response: {error}", retryable=False
479
+ ) from error
480
+ stripped = _strip_json(message if isinstance(message, str) else "")
481
+ try:
482
+ data = json.loads(stripped)
483
+ except json.JSONDecodeError as error:
484
+ raise OpenRouterError(
485
+ f"model returned non-JSON output: {stripped[:80]!r}", retryable=False
486
+ ) from error
487
+ if not isinstance(data, dict):
488
+ raise OpenRouterError("model JSON output is not an object", retryable=False)
489
+ return data
490
+ raise OpenRouterError(last_error, retryable=True)
File without changes
@@ -0,0 +1,10 @@
1
+ Metadata-Version: 2.4
2
+ Name: voxora-ai-runtime
3
+ Version: 0.1.0
4
+ Summary: Deterministic mock AI agent runtime contract for Voxora Studio
5
+ Requires-Python: >=3.9
6
+ Requires-Dist: httpx>=0.27.2
7
+ Requires-Dist: typing-extensions>=4.12.2
8
+ Provides-Extra: dev
9
+ Requires-Dist: pytest<9,>=8; extra == "dev"
10
+ Requires-Dist: httpx>=0.27.2; extra == "dev"
@@ -0,0 +1,12 @@
1
+ pyproject.toml
2
+ src/voxora_ai/__init__.py
3
+ src/voxora_ai/engine.py
4
+ src/voxora_ai/openrouter.py
5
+ src/voxora_ai/py.typed
6
+ src/voxora_ai_runtime.egg-info/PKG-INFO
7
+ src/voxora_ai_runtime.egg-info/SOURCES.txt
8
+ src/voxora_ai_runtime.egg-info/dependency_links.txt
9
+ src/voxora_ai_runtime.egg-info/requires.txt
10
+ src/voxora_ai_runtime.egg-info/top_level.txt
11
+ tests/test_engine.py
12
+ tests/test_openrouter.py
@@ -0,0 +1,6 @@
1
+ httpx>=0.27.2
2
+ typing-extensions>=4.12.2
3
+
4
+ [dev]
5
+ pytest<9,>=8
6
+ httpx>=0.27.2
@@ -0,0 +1,71 @@
1
+ """Tests for the deterministic mock agent backend."""
2
+
3
+ import hashlib
4
+
5
+ import pytest
6
+
7
+ voxora_ai = pytest.importorskip(
8
+ "voxora_ai",
9
+ reason="services/ai-runtime tests import via their own pythonpath fixture",
10
+ )
11
+
12
+
13
+ def test_capabilities_are_honest() -> None:
14
+ agent = voxora_ai.MockAgent()
15
+ assert agent.capabilities == {
16
+ "real_llm": False,
17
+ "audio_mixing": False,
18
+ "barge_in_vad": False,
19
+ "scripted": True,
20
+ }
21
+
22
+
23
+ def test_start_returns_first_script_turn() -> None:
24
+ agent = voxora_ai.MockAgent()
25
+ reply = agent.start()
26
+ assert reply.turn_index == 1
27
+ assert reply.text.startswith("Hello, this is a simulated call")
28
+ assert reply.ended is False
29
+
30
+
31
+ def test_respond_without_start_raises() -> None:
32
+ agent = voxora_ai.MockAgent()
33
+ with pytest.raises(voxora_ai.AgentTurnError):
34
+ agent.respond("hello")
35
+
36
+
37
+ def test_script_advances_and_ends() -> None:
38
+ agent = voxora_ai.MockAgent()
39
+ agent.start()
40
+ second = agent.respond("yes")
41
+ assert second.turn_index == 2
42
+ assert second.ended is False
43
+ third = agent.respond("sure")
44
+ assert third.turn_index == 3
45
+ assert third.ended is True
46
+
47
+
48
+ def test_user_goodbye_ends_immediately() -> None:
49
+ agent = voxora_ai.MockAgent()
50
+ agent.start()
51
+ reply = agent.respond("please end call, goodbye")
52
+ assert reply.ended is True
53
+ assert "Goodbye" in reply.text
54
+
55
+
56
+ def test_script_exhaustion_closes_call() -> None:
57
+ agent = voxora_ai.MockAgent(script=["First turn."])
58
+ agent.start()
59
+ reply = agent.respond("go on")
60
+ assert reply.turn_index == 2
61
+ assert reply.ended is True
62
+
63
+
64
+ def test_latency_is_deterministic_and_hash_derived() -> None:
65
+ agent = voxora_ai.MockAgent()
66
+ first = agent.start()
67
+ again = voxora_ai.MockAgent().start()
68
+ assert first.latency_simulated_ms == again.latency_simulated_ms
69
+ digest = hashlib.sha256(first.text.encode("utf-8")).digest()
70
+ expected = 120.0 + digest[0] % 330
71
+ assert first.latency_simulated_ms == expected
@@ -0,0 +1,287 @@
1
+ """OpenRouter agent contract tests (ported/adapted from PyInterviewBot).
2
+
3
+ The live OpenRouter service is not part of this test scope; the fake transport
4
+ pins the documented request/response shapes we implement against, including
5
+ the OpenRouter usage/billing fields (`usage.include` => per-call `cost`).
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ from typing import Any, Dict, List, Optional
12
+
13
+ import pytest
14
+
15
+ voxora_ai = pytest.importorskip(
16
+ "voxora_ai",
17
+ reason="services/ai-runtime tests import via their own pythonpath fixture",
18
+ )
19
+ try:
20
+ import httpx
21
+ except ImportError: # pragma: no cover
22
+ pytest.skip("httpx not installed", allow_module_level=True)
23
+
24
+ from voxora_ai.openrouter import ( # noqa: E402 - below guarded pytest.skip
25
+ DEFAULT_BASE_URL,
26
+ OpenRouterAgent,
27
+ create_agent_from_env,
28
+ )
29
+
30
+ REPLY = {"text": "Hello, what matters most to you?", "end_call": False}
31
+ DECISION = {
32
+ "choices": [
33
+ {
34
+ "message": {"content": json.dumps(REPLY)},
35
+ }
36
+ ],
37
+ "usage": {"prompt_tokens": 120, "completion_tokens": 60, "total_tokens": 180, "cost": "0.0025"},
38
+ }
39
+
40
+
41
+ def make_client(monkeypatch: pytest.MonkeyPatch, handler) -> Any:
42
+ transport = httpx.MockTransport(handler)
43
+ return httpx.Client(transport=transport, base_url="https://openrouter.test/api/v1")
44
+
45
+
46
+ def build_agent(client: Any, **overrides: Any) -> OpenRouterAgent:
47
+ kwargs = dict(api_key="sk-or-secret", model="anthropic/claude-3.5-sonnet", client=client)
48
+ kwargs.update(overrides)
49
+ return OpenRouterAgent(**kwargs)
50
+
51
+
52
+ def test_request_contract_and_usage_billing_capture(monkeypatch: pytest.MonkeyPatch) -> None:
53
+ captured: Dict[str, Any] = {}
54
+
55
+ def handler(request: httpx.Request) -> httpx.Response:
56
+ captured["path"] = request.url.path
57
+ captured["auth"] = request.headers.get("authorization")
58
+ captured["title"] = request.headers.get("x-title")
59
+ body = json.loads(request.read())
60
+ captured["body"] = body
61
+ captured["usage_costs"] = bool(body.get("usage", {}).get("include"))
62
+ return httpx.Response(200, json=DECISION)
63
+
64
+ agent = build_agent(
65
+ make_client(monkeypatch, handler),
66
+ system_prompt="You are a campaign voice agent.",
67
+ app_name="Voxora Studio",
68
+ )
69
+ agent.start()
70
+ reply = agent.respond("I am listening.")
71
+ assert reply.text == REPLY["text"] and reply.ended is False
72
+ assert captured["path"] == "/api/v1/chat/completions"
73
+ assert captured["auth"] == "Bearer sk-or-secret"
74
+ assert captured["title"] == "Voxora Studio"
75
+ assert captured["body"]["model"] == "anthropic/claude-3.5-sonnet"
76
+ assert captured["body"]["response_format"] == {"type": "json_object"}
77
+ assert captured["usage_costs"] is True
78
+ # Billing per call, honestly accumulated from OpenRouter's usage response.
79
+ assert agent.last_usage["cost_usd"] == 0.0025
80
+ assert agent.last_usage["total_tokens"] == 180
81
+ report = agent.usage_report()
82
+ # start + respond = two model calls billed by OpenRouter.
83
+ assert report["cost_usd"] == 0.005 and report["total_tokens"] == 360.0
84
+ assert agent.capabilities["real_llm"] is True
85
+
86
+
87
+ def test_missing_cost_is_recorded_as_zero_not_fabricated(monkeypatch: pytest.MonkeyPatch) -> None:
88
+ body = dict(DECISION)
89
+ body["usage"] = {"prompt_tokens": 10, "completion_tokens": 5}
90
+
91
+ def handler(_request: httpx.Request) -> httpx.Response:
92
+ return httpx.Response(200, json=body)
93
+
94
+ agent = build_agent(make_client(monkeypatch, handler))
95
+ agent.start()
96
+ assert agent.last_usage["cost_usd"] == 0.0
97
+ assert agent.last_usage["total_tokens"] == 15
98
+
99
+
100
+ def test_retries_429_then_succeeds(monkeypatch: pytest.MonkeyPatch) -> None:
101
+ calls = {"count": 0}
102
+
103
+ def handler(_request: httpx.Request) -> httpx.Response:
104
+ calls["count"] += 1
105
+ if calls["count"] == 1:
106
+ return httpx.Response(429, json={"error": "rate limited"})
107
+ return httpx.Response(200, json=DECISION)
108
+
109
+ agent = build_agent(make_client(monkeypatch, handler), max_retries=1, retry_base_delay=0)
110
+ agent.start()
111
+ assert calls["count"] == 2
112
+ assert agent.respond("yes").ended is False
113
+
114
+
115
+ def test_retries_invalid_json_with_explicit_instruction(monkeypatch: pytest.MonkeyPatch) -> None:
116
+ calls: List[str] = []
117
+
118
+ def handler(request: httpx.Request) -> httpx.Response:
119
+ body = json.loads(request.read())
120
+ if len(body["messages"]) > 2:
121
+ calls.append("corrected")
122
+ return httpx.Response(200, json=DECISION)
123
+ return httpx.Response(200, json={"choices": [{"message": {"content": "not json at all"}}]})
124
+
125
+ agent = build_agent(make_client(monkeypatch, handler), max_retries=1, retry_base_delay=0)
126
+ agent.start()
127
+ assert calls == ["corrected"]
128
+
129
+
130
+ def test_response_format_fallback_on_400(monkeypatch: pytest.MonkeyPatch) -> None:
131
+ seen: List[Any] = []
132
+
133
+ def handler(request: httpx.Request) -> httpx.Response:
134
+ body = json.loads(request.read())
135
+ seen.append(body.get("response_format"))
136
+ if "response_format" in body:
137
+ return httpx.Response(400, json={"error": "response_format unsupported"})
138
+ return httpx.Response(200, json=DECISION)
139
+
140
+ agent = build_agent(make_client(monkeypatch, handler), max_retries=1)
141
+ agent.start()
142
+ assert seen[0] == {"type": "json_object"} and seen[1] is None
143
+ assert agent.respond("ok").text == REPLY["text"]
144
+
145
+
146
+ def test_end_call_flag_and_local_end_keywords(monkeypatch: pytest.MonkeyPatch) -> None:
147
+ ended_body = {
148
+ "choices": [{"message": {"content": json.dumps({"text": "Goodbye.", "end_call": True})}}],
149
+ "usage": {},
150
+ }
151
+
152
+ def handler(_request: httpx.Request) -> httpx.Response:
153
+ return httpx.Response(200, json=ended_body)
154
+
155
+ agent = build_agent(make_client(monkeypatch, handler), max_retries=0)
156
+ agent.start()
157
+ reply = agent.respond("wrap it up")
158
+ assert reply.ended is True and reply.text == "Goodbye."
159
+
160
+ # Local belt-and-suspenders: end keywords close without model access.
161
+ kw_agent = build_agent(make_client(monkeypatch, handler))
162
+ kw_agent.start()
163
+ kw_agent._client = httpx.Client(
164
+ transport=httpx.MockTransport(lambda _req: pytest.fail("network reached after end")),
165
+ base_url=DEFAULT_BASE_URL,
166
+ )
167
+ reply = kw_agent.respond("please stop calling, goodbye")
168
+ assert reply.ended is True and "Goodbye" in reply.text
169
+
170
+
171
+ def test_health_and_key_model_requirements(monkeypatch: pytest.MonkeyPatch) -> None:
172
+ def handler(_request: httpx.Request) -> httpx.Response:
173
+ return httpx.Response(200, json={"data": True})
174
+
175
+ agent = build_agent(make_client(monkeypatch, handler))
176
+ assert agent.health() is True
177
+ monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
178
+ monkeypatch.delenv("OPENROUTER_MODEL", raising=False)
179
+ def handler_dead(_r: httpx.Request) -> httpx.Response:
180
+ pytest.fail("should not reach network")
181
+ with pytest.raises(ValueError) as key_error:
182
+ OpenRouterAgent(api_key=None, model=None, client=make_client(monkeypatch, handler_dead))
183
+ assert "OPENROUTER_API_KEY" in str(key_error.value)
184
+
185
+
186
+ def test_agent_brain_takes_over_turns_and_can_end(monkeypatch: pytest.MonkeyPatch) -> None:
187
+ from voxora_ai.engine import AgentBrain, AgentReply
188
+
189
+ net_calls = {"n": 0}
190
+
191
+ def handler(_request: httpx.Request) -> httpx.Response:
192
+ net_calls["n"] += 1
193
+ return httpx.Response(200, json=DECISION)
194
+
195
+ class InterviewBrain:
196
+ """What a downstream interview product would implement."""
197
+
198
+ def __init__(self) -> None:
199
+ self.turns = 0
200
+
201
+ def respond(self, _user_text: str, history: List[Dict[str, str]]) -> Optional[AgentReply]:
202
+ self.turns += 1
203
+ if self.turns >= 2:
204
+ return AgentReply("Evidence collected; ending per interview policy.", ended=True, turn_index=len(history) + 1)
205
+ return None # defer to Voxora's OpenRouter phrasing
206
+
207
+ brain = InterviewBrain()
208
+ assert isinstance(brain, AgentBrain)
209
+ agent = build_agent(make_client(monkeypatch, handler), brain=brain)
210
+ agent.start()
211
+ first = agent.respond("fine, thanks")
212
+ assert brain.turns == 1
213
+ assert "Hello, what matters" in first.text and first.ended is False # engine phrased it
214
+ second = agent.respond("anything else?")
215
+ assert brain.turns == 2 and net_calls["n"] == 2 # brain turn, zero extra model calls
216
+ assert second.ended is True and "Evidence collected" in second.text
217
+ assert agent._started is False
218
+
219
+
220
+ def test_provider_selection_is_explicit_and_fail_closed(monkeypatch: pytest.MonkeyPatch) -> None:
221
+ monkeypatch.delenv("VOXORA_LLM_PROVIDER", raising=False)
222
+ assert type(create_agent_from_env({})).__name__ == "MockAgent"
223
+ with pytest.raises(ValueError) as fail_closed:
224
+ create_agent_from_env({"VOXORA_LLM_PROVIDER": "openrouter"})
225
+ assert "OPENROUTER_API_KEY" in str(fail_closed.value)
226
+ with pytest.raises(ValueError):
227
+ create_agent_from_env({"VOXORA_LLM_PROVIDER": "gpt4-turbo"})
228
+
229
+
230
+ # ---------------------------------------------------------------------------
231
+ # Regression (audit 2026-11-04, V1): the default transport must be the
232
+ # synchronous `httpx.Client`. Voxora's agent/decide contract is synchronous;
233
+ # an AsyncClient default returned unawaited coroutines and crashed every
234
+ # default-constructor call path (e.g. `/api/v1/ai/decide` 500s).
235
+
236
+
237
+ def _default_env(monkeypatch: pytest.MonkeyPatch) -> None:
238
+ monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-secret")
239
+ monkeypatch.setenv("OPENROUTER_MODEL", "anthropic/claude-3.5-sonnet")
240
+
241
+
242
+ def test_default_transport_is_synchronous_client(monkeypatch: pytest.MonkeyPatch) -> None:
243
+ _default_env(monkeypatch)
244
+ agent = OpenRouterAgent()
245
+ assert isinstance(agent._client, httpx.Client)
246
+ assert not isinstance(agent._client, httpx.AsyncClient)
247
+
248
+ from voxora_ai.openrouter import OpenRouterLLM
249
+
250
+ llm = OpenRouterLLM()
251
+ assert isinstance(llm._client, httpx.Client)
252
+ assert not isinstance(llm._client, httpx.AsyncClient)
253
+
254
+
255
+ def test_llm_decide_round_trip_pins_route_contract(monkeypatch: pytest.MonkeyPatch) -> None:
256
+ from voxora_ai.openrouter import OpenRouterLLM
257
+
258
+ captured: Dict[str, Any] = {}
259
+
260
+ def handler(request: httpx.Request) -> httpx.Response:
261
+ captured["path"] = request.url.path
262
+ captured["auth"] = request.headers.get("authorization")
263
+ captured["body"] = json.loads(request.read())
264
+ return httpx.Response(
265
+ 200,
266
+ json={
267
+ "choices": [{"message": {"content": json.dumps({"next_action": "probe"})}}],
268
+ "usage": {"prompt_tokens": 30, "completion_tokens": 12, "total_tokens": 42, "cost": "0.0007"},
269
+ },
270
+ )
271
+
272
+ llm = OpenRouterLLM(
273
+ api_key="sk-or-secret",
274
+ model="anthropic/claude-3.5-sonnet",
275
+ client=httpx.Client(transport=httpx.MockTransport(handler), base_url=DEFAULT_BASE_URL),
276
+ )
277
+ decision = llm.decide("system prompt", "user prompt", temperature=0.2)
278
+ assert decision == {"next_action": "probe"}
279
+ assert captured["path"] == "/api/v1/chat/completions"
280
+ assert captured["auth"] == "Bearer sk-or-secret"
281
+ assert captured["body"]["messages"][0] == {"role": "system", "content": "system prompt"}
282
+ assert captured["body"]["messages"][1] == {"role": "user", "content": "user prompt"}
283
+ assert captured["body"]["usage"] == {"include": True}
284
+ assert captured["body"]["response_format"] == {"type": "json_object"}
285
+ assert captured["body"]["temperature"] == 0.2
286
+ usage = llm.usage_report()
287
+ assert usage["total_tokens"] == 42.0 and usage["cost_usd"] == 0.0007