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.
- voxora_ai_runtime-0.1.0/PKG-INFO +10 -0
- voxora_ai_runtime-0.1.0/pyproject.toml +28 -0
- voxora_ai_runtime-0.1.0/setup.cfg +4 -0
- voxora_ai_runtime-0.1.0/src/voxora_ai/__init__.py +23 -0
- voxora_ai_runtime-0.1.0/src/voxora_ai/engine.py +109 -0
- voxora_ai_runtime-0.1.0/src/voxora_ai/openrouter.py +490 -0
- voxora_ai_runtime-0.1.0/src/voxora_ai/py.typed +0 -0
- voxora_ai_runtime-0.1.0/src/voxora_ai_runtime.egg-info/PKG-INFO +10 -0
- voxora_ai_runtime-0.1.0/src/voxora_ai_runtime.egg-info/SOURCES.txt +12 -0
- voxora_ai_runtime-0.1.0/src/voxora_ai_runtime.egg-info/dependency_links.txt +1 -0
- voxora_ai_runtime-0.1.0/src/voxora_ai_runtime.egg-info/requires.txt +6 -0
- voxora_ai_runtime-0.1.0/src/voxora_ai_runtime.egg-info/top_level.txt +1 -0
- voxora_ai_runtime-0.1.0/tests/test_engine.py +71 -0
- voxora_ai_runtime-0.1.0/tests/test_openrouter.py +287 -0
|
@@ -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,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 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
voxora_ai
|
|
@@ -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
|