nexus-coding-agent 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- nexus/__init__.py +4 -0
- nexus/application/__init__.py +2 -0
- nexus/application/approval_service.py +130 -0
- nexus/application/diff_service.py +177 -0
- nexus/application/event_publisher.py +180 -0
- nexus/application/execution_context.py +29 -0
- nexus/application/execution_ledger.py +126 -0
- nexus/application/model_call_context.py +29 -0
- nexus/application/observed_model_gateway.py +194 -0
- nexus/application/plan_approval_service.py +250 -0
- nexus/application/planning.py +668 -0
- nexus/application/runtime.py +624 -0
- nexus/application/session_service.py +411 -0
- nexus/application/structured_output.py +96 -0
- nexus/application/telemetry.py +396 -0
- nexus/application/telemetry_subscriber.py +216 -0
- nexus/application/tool_runtime.py +496 -0
- nexus/application/tracing_dispatcher.py +283 -0
- nexus/application/validation.py +293 -0
- nexus/config/__init__.py +17 -0
- nexus/config/loader.py +253 -0
- nexus/config/models.py +310 -0
- nexus/context/__init__.py +6 -0
- nexus/context/budget.py +24 -0
- nexus/context/builder.py +92 -0
- nexus/context/chunking.py +65 -0
- nexus/context/explorer.py +246 -0
- nexus/context/integration.py +63 -0
- nexus/context/manager.py +328 -0
- nexus/context/retrieval.py +261 -0
- nexus/domain/__init__.py +2 -0
- nexus/domain/agent_decision.py +113 -0
- nexus/domain/agent_state.py +49 -0
- nexus/domain/approvals.py +64 -0
- nexus/domain/context.py +108 -0
- nexus/domain/exploration.py +86 -0
- nexus/domain/mcp.py +51 -0
- nexus/domain/model.py +173 -0
- nexus/domain/observability.py +326 -0
- nexus/domain/persistence.py +122 -0
- nexus/domain/planning.py +329 -0
- nexus/domain/ports/__init__.py +61 -0
- nexus/domain/ports/agent_decision.py +9 -0
- nexus/domain/ports/approval_unit_of_work.py +27 -0
- nexus/domain/ports/checkpoint_provider.py +11 -0
- nexus/domain/ports/context.py +71 -0
- nexus/domain/ports/events.py +21 -0
- nexus/domain/ports/graph_runtime.py +30 -0
- nexus/domain/ports/mcp.py +23 -0
- nexus/domain/ports/model_gateway.py +21 -0
- nexus/domain/ports/model_input_budget.py +15 -0
- nexus/domain/ports/planning.py +62 -0
- nexus/domain/ports/repositories.py +54 -0
- nexus/domain/ports/repository_context.py +18 -0
- nexus/domain/ports/session_unit_of_work.py +33 -0
- nexus/domain/ports/skills.py +41 -0
- nexus/domain/ports/tooling.py +39 -0
- nexus/domain/ports/tracer.py +13 -0
- nexus/domain/ports/validation.py +32 -0
- nexus/domain/runtime_events.py +445 -0
- nexus/domain/skills.py +129 -0
- nexus/domain/tooling.py +163 -0
- nexus/domain/validation.py +161 -0
- nexus/errors/__init__.py +82 -0
- nexus/evaluation/__init__.py +7 -0
- nexus/evaluation/assertions.py +4 -0
- nexus/evaluation/evaluator.py +263 -0
- nexus/evaluation/fixtures.py +36 -0
- nexus/evaluation/harness.py +606 -0
- nexus/evaluation/loader.py +415 -0
- nexus/evaluation/metrics.py +27 -0
- nexus/evaluation/models.py +362 -0
- nexus/evaluation/report.py +43 -0
- nexus/evaluation/runner.py +480 -0
- nexus/infrastructure/__init__.py +2 -0
- nexus/infrastructure/asyncio_compat.py +13 -0
- nexus/infrastructure/bootstrap/__init__.py +17 -0
- nexus/infrastructure/bootstrap/composition.py +663 -0
- nexus/infrastructure/checkpoint/__init__.py +5 -0
- nexus/infrastructure/checkpoint/postgres.py +62 -0
- nexus/infrastructure/database.py +39 -0
- nexus/infrastructure/embedding.py +61 -0
- nexus/infrastructure/graph/__init__.py +6 -0
- nexus/infrastructure/graph/day4_runtime.py +966 -0
- nexus/infrastructure/graph/langgraph_runtime.py +172 -0
- nexus/infrastructure/mcp/__init__.py +5 -0
- nexus/infrastructure/mcp/manager.py +380 -0
- nexus/infrastructure/model_gateway/__init__.py +6 -0
- nexus/infrastructure/model_gateway/openai_compatible.py +345 -0
- nexus/infrastructure/observability/__init__.py +7 -0
- nexus/infrastructure/observability/console.py +31 -0
- nexus/infrastructure/observability/langsmith.py +236 -0
- nexus/infrastructure/observability/structured_logger.py +70 -0
- nexus/infrastructure/persistence/__init__.py +13 -0
- nexus/infrastructure/persistence/approval_unit_of_work.py +74 -0
- nexus/infrastructure/persistence/models.py +146 -0
- nexus/infrastructure/persistence/repositories.py +326 -0
- nexus/infrastructure/persistence/unit_of_work.py +82 -0
- nexus/infrastructure/repository_files.py +117 -0
- nexus/infrastructure/sandbox/__init__.py +5 -0
- nexus/infrastructure/sandbox/local_process.py +353 -0
- nexus/infrastructure/semantic.py +276 -0
- nexus/infrastructure/semantic_models.py +56 -0
- nexus/interfaces/__init__.py +2 -0
- nexus/interfaces/cli/__init__.py +2 -0
- nexus/interfaces/cli/__main__.py +6 -0
- nexus/interfaces/cli/app.py +266 -0
- nexus/interfaces/cli/renderer.py +118 -0
- nexus/security/__init__.py +14 -0
- nexus/security/approval_policies.py +73 -0
- nexus/security/command_policy.py +117 -0
- nexus/security/executables.py +107 -0
- nexus/security/git_commands.py +65 -0
- nexus/security/workspace.py +93 -0
- nexus/skills/__init__.py +7 -0
- nexus/skills/builtin/__init__.py +1 -0
- nexus/skills/builtin/debug-python/SKILL.md +26 -0
- nexus/skills/builtin/review-repository/SKILL.md +26 -0
- nexus/skills/builtin/write-tests/SKILL.md +26 -0
- nexus/skills/loader.py +439 -0
- nexus/skills/registry.py +146 -0
- nexus/skills/selector.py +152 -0
- nexus/tools/__init__.py +6 -0
- nexus/tools/editing.py +312 -0
- nexus/tools/mcp.py +160 -0
- nexus/tools/native.py +654 -0
- nexus/tools/registry.py +27 -0
- nexus_coding_agent-0.1.0.dist-info/METADATA +142 -0
- nexus_coding_agent-0.1.0.dist-info/RECORD +131 -0
- nexus_coding_agent-0.1.0.dist-info/WHEEL +4 -0
- nexus_coding_agent-0.1.0.dist-info/entry_points.txt +2 -0
|
@@ -0,0 +1,345 @@
|
|
|
1
|
+
"""LangChain-backed adapter for the approved OpenAI-compatible provider."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import AsyncIterator, Mapping, Sequence
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
from langchain_openai import ChatOpenAI
|
|
9
|
+
|
|
10
|
+
from nexus.application.model_call_context import current_model_call_phase
|
|
11
|
+
from nexus.config.models import SUPPORTED_MODEL_PROVIDER, RuntimeConfig
|
|
12
|
+
from nexus.domain.model import (
|
|
13
|
+
ModelCallPhase,
|
|
14
|
+
ModelChunk,
|
|
15
|
+
ModelMessage,
|
|
16
|
+
ModelResponse,
|
|
17
|
+
TokenUsage,
|
|
18
|
+
UsageAvailability,
|
|
19
|
+
)
|
|
20
|
+
from nexus.errors import ConfigurationError, ModelError
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class OpenAICompatibleModelGateway:
|
|
24
|
+
"""Normalize LangChain/OpenAI-compatible calls into Nexus-owned values."""
|
|
25
|
+
|
|
26
|
+
def __init__(self, config: RuntimeConfig) -> None:
|
|
27
|
+
self._config = config
|
|
28
|
+
self._client: ChatOpenAI | None = None
|
|
29
|
+
|
|
30
|
+
async def complete(self, messages: Sequence[ModelMessage]) -> ModelResponse:
|
|
31
|
+
try:
|
|
32
|
+
response = await self._get_client().ainvoke(
|
|
33
|
+
self._convert_messages(messages),
|
|
34
|
+
**self._structured_output_options(),
|
|
35
|
+
)
|
|
36
|
+
content = _normalize_content(response.content)
|
|
37
|
+
except ConfigurationError:
|
|
38
|
+
raise
|
|
39
|
+
except Exception as exc:
|
|
40
|
+
raise ModelError(
|
|
41
|
+
"The configured model request failed.",
|
|
42
|
+
retryable=True,
|
|
43
|
+
) from exc
|
|
44
|
+
if not content.strip():
|
|
45
|
+
raise ModelError(
|
|
46
|
+
"The configured model returned empty output.",
|
|
47
|
+
code="EMPTY_MODEL_OUTPUT",
|
|
48
|
+
)
|
|
49
|
+
return ModelResponse(content=content, usage=_normalize_usage(response.usage_metadata))
|
|
50
|
+
|
|
51
|
+
async def stream(self, messages: Sequence[ModelMessage]) -> AsyncIterator[ModelChunk]:
|
|
52
|
+
pending_content: str | None = None
|
|
53
|
+
terminal_usage: TokenUsage | None = None
|
|
54
|
+
try:
|
|
55
|
+
async for chunk in self._get_client().astream(self._convert_messages(messages)):
|
|
56
|
+
if pending_content is not None:
|
|
57
|
+
yield ModelChunk(content=pending_content)
|
|
58
|
+
pending_content = _normalize_content(chunk.content)
|
|
59
|
+
usage = _normalize_usage(chunk.usage_metadata)
|
|
60
|
+
if usage is not None:
|
|
61
|
+
terminal_usage = usage
|
|
62
|
+
if pending_content is not None:
|
|
63
|
+
yield ModelChunk(content=pending_content, usage=terminal_usage)
|
|
64
|
+
except ConfigurationError:
|
|
65
|
+
raise
|
|
66
|
+
except Exception as exc:
|
|
67
|
+
raise ModelError(
|
|
68
|
+
"The configured model stream failed.",
|
|
69
|
+
retryable=True,
|
|
70
|
+
) from exc
|
|
71
|
+
|
|
72
|
+
def _get_client(self) -> ChatOpenAI:
|
|
73
|
+
if self._client is not None:
|
|
74
|
+
return self._client
|
|
75
|
+
if self._config.model_provider != SUPPORTED_MODEL_PROVIDER:
|
|
76
|
+
raise ConfigurationError("Only the openai_compatible provider is supported on Day 1.")
|
|
77
|
+
if self._config.model_name is None:
|
|
78
|
+
raise ConfigurationError("Configure a model name before running nexus chat.")
|
|
79
|
+
if self._config.model_api_key is None:
|
|
80
|
+
raise ConfigurationError("Set NEXUS_MODEL_API_KEY before running nexus chat.")
|
|
81
|
+
|
|
82
|
+
try:
|
|
83
|
+
self._client = ChatOpenAI(
|
|
84
|
+
model=self._config.model_name,
|
|
85
|
+
base_url=self._config.model_base_url,
|
|
86
|
+
api_key=self._config.model_api_key,
|
|
87
|
+
)
|
|
88
|
+
except Exception as exc:
|
|
89
|
+
raise ModelError("The configured model could not be initialized.") from exc
|
|
90
|
+
return self._client
|
|
91
|
+
|
|
92
|
+
def _structured_output_options(self) -> dict[str, Any]:
|
|
93
|
+
if not _is_qwen_3_7_plus(self._config.model_name):
|
|
94
|
+
return {}
|
|
95
|
+
try:
|
|
96
|
+
phase = current_model_call_phase()
|
|
97
|
+
except RuntimeError:
|
|
98
|
+
return {}
|
|
99
|
+
response_format = _response_format_for_phase(phase)
|
|
100
|
+
if response_format is None:
|
|
101
|
+
return {}
|
|
102
|
+
return {
|
|
103
|
+
"response_format": response_format,
|
|
104
|
+
"extra_body": {"enable_thinking": False},
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
@staticmethod
|
|
108
|
+
def _convert_messages(messages: Sequence[ModelMessage]) -> list[tuple[str, str]]:
|
|
109
|
+
return [(message.role, message.content) for message in messages]
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _normalize_content(content: Any) -> str:
|
|
113
|
+
if isinstance(content, str):
|
|
114
|
+
return content
|
|
115
|
+
if not isinstance(content, list):
|
|
116
|
+
return ""
|
|
117
|
+
|
|
118
|
+
text_parts: list[str] = []
|
|
119
|
+
for block in content:
|
|
120
|
+
if isinstance(block, str):
|
|
121
|
+
text_parts.append(block)
|
|
122
|
+
elif isinstance(block, dict) and block.get("type") == "text":
|
|
123
|
+
text = block.get("text")
|
|
124
|
+
if isinstance(text, str):
|
|
125
|
+
text_parts.append(text)
|
|
126
|
+
return "".join(text_parts)
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def _normalize_usage(value: object) -> TokenUsage | None:
|
|
130
|
+
if value is None:
|
|
131
|
+
return None
|
|
132
|
+
if not isinstance(value, Mapping):
|
|
133
|
+
return TokenUsage.unavailable()
|
|
134
|
+
raw_values = (
|
|
135
|
+
value.get("input_tokens"),
|
|
136
|
+
value.get("output_tokens"),
|
|
137
|
+
value.get("total_tokens"),
|
|
138
|
+
)
|
|
139
|
+
normalized = tuple(
|
|
140
|
+
item
|
|
141
|
+
if isinstance(item, int) and not isinstance(item, bool) and item >= 0
|
|
142
|
+
else None
|
|
143
|
+
for item in raw_values
|
|
144
|
+
)
|
|
145
|
+
input_tokens, output_tokens, total_tokens = normalized
|
|
146
|
+
if (
|
|
147
|
+
input_tokens is not None
|
|
148
|
+
and output_tokens is not None
|
|
149
|
+
and total_tokens is not None
|
|
150
|
+
and total_tokens != input_tokens + output_tokens
|
|
151
|
+
):
|
|
152
|
+
normalized = (input_tokens, output_tokens, None)
|
|
153
|
+
known = sum(item is not None for item in normalized)
|
|
154
|
+
if known == 0:
|
|
155
|
+
return TokenUsage.unavailable()
|
|
156
|
+
availability = (
|
|
157
|
+
UsageAvailability.REPORTED if known == 3 else UsageAvailability.PARTIAL
|
|
158
|
+
)
|
|
159
|
+
return TokenUsage(normalized[0], normalized[1], normalized[2], availability)
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def _is_qwen_3_7_plus(model_name: str | None) -> bool:
|
|
163
|
+
return model_name == "qwen3.7-plus" or (
|
|
164
|
+
model_name is not None and model_name.startswith("qwen3.7-plus-")
|
|
165
|
+
)
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def _response_format_for_phase(phase: ModelCallPhase) -> dict[str, Any] | None:
|
|
169
|
+
if phase in {ModelCallPhase.PLAN, ModelCallPhase.REPLAN}:
|
|
170
|
+
return _json_schema_response_format("nexus_plan", _plan_schema())
|
|
171
|
+
if phase is ModelCallPhase.REPAIR:
|
|
172
|
+
return _json_schema_response_format("nexus_repair", _repair_schema())
|
|
173
|
+
if phase is ModelCallPhase.AGENT_STEP:
|
|
174
|
+
return _json_schema_response_format("nexus_agent_decision", _agent_schema())
|
|
175
|
+
if phase is ModelCallPhase.SKILL_SELECTION:
|
|
176
|
+
return _json_schema_response_format("nexus_skill_selection", _skill_selection_schema())
|
|
177
|
+
return None
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def _json_schema_response_format(name: str, schema: dict[str, Any]) -> dict[str, Any]:
|
|
181
|
+
return {
|
|
182
|
+
"type": "json_schema",
|
|
183
|
+
"json_schema": {
|
|
184
|
+
"name": name,
|
|
185
|
+
"strict": True,
|
|
186
|
+
"schema": schema,
|
|
187
|
+
},
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
def _plan_step_schema() -> dict[str, Any]:
|
|
192
|
+
return {
|
|
193
|
+
"oneOf": [
|
|
194
|
+
_plan_step_variant_schema(
|
|
195
|
+
tool_name={
|
|
196
|
+
"type": "string",
|
|
197
|
+
"enum": ["apply_patch", "write_file"],
|
|
198
|
+
},
|
|
199
|
+
target_paths={
|
|
200
|
+
"type": "array",
|
|
201
|
+
"items": {"type": "string"},
|
|
202
|
+
"minItems": 1,
|
|
203
|
+
"maxItems": 1,
|
|
204
|
+
},
|
|
205
|
+
command_argv={"type": "null"},
|
|
206
|
+
command_cwd={"type": "null"},
|
|
207
|
+
),
|
|
208
|
+
_plan_step_variant_schema(
|
|
209
|
+
tool_name={"type": "string", "enum": ["shell"]},
|
|
210
|
+
target_paths={
|
|
211
|
+
"type": "array",
|
|
212
|
+
"items": {"type": "string"},
|
|
213
|
+
"maxItems": 0,
|
|
214
|
+
},
|
|
215
|
+
command_argv={
|
|
216
|
+
"type": "array",
|
|
217
|
+
"items": {"type": "string", "minLength": 1},
|
|
218
|
+
"minItems": 1,
|
|
219
|
+
},
|
|
220
|
+
command_cwd={"type": "string", "minLength": 1},
|
|
221
|
+
),
|
|
222
|
+
_plan_step_variant_schema(
|
|
223
|
+
tool_name={
|
|
224
|
+
"type": ["string", "null"],
|
|
225
|
+
"not": {"enum": ["apply_patch", "write_file", "shell"]},
|
|
226
|
+
},
|
|
227
|
+
target_paths={
|
|
228
|
+
"type": "array",
|
|
229
|
+
"items": {"type": "string"},
|
|
230
|
+
"maxItems": 0,
|
|
231
|
+
},
|
|
232
|
+
command_argv={"type": "null"},
|
|
233
|
+
command_cwd={"type": "null"},
|
|
234
|
+
),
|
|
235
|
+
]
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
def _plan_step_variant_schema(
|
|
240
|
+
*,
|
|
241
|
+
tool_name: dict[str, Any],
|
|
242
|
+
target_paths: dict[str, Any],
|
|
243
|
+
command_argv: dict[str, Any],
|
|
244
|
+
command_cwd: dict[str, Any],
|
|
245
|
+
) -> dict[str, Any]:
|
|
246
|
+
return {
|
|
247
|
+
"type": "object",
|
|
248
|
+
"additionalProperties": False,
|
|
249
|
+
"properties": {
|
|
250
|
+
"description": {"type": "string", "minLength": 1},
|
|
251
|
+
"tool_name": tool_name,
|
|
252
|
+
"target_paths": target_paths,
|
|
253
|
+
"command_argv": command_argv,
|
|
254
|
+
"command_cwd": command_cwd,
|
|
255
|
+
},
|
|
256
|
+
"required": [
|
|
257
|
+
"description",
|
|
258
|
+
"tool_name",
|
|
259
|
+
"target_paths",
|
|
260
|
+
"command_argv",
|
|
261
|
+
"command_cwd",
|
|
262
|
+
],
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
def _plan_schema() -> dict[str, Any]:
|
|
267
|
+
return {
|
|
268
|
+
"type": "object",
|
|
269
|
+
"additionalProperties": False,
|
|
270
|
+
"properties": {
|
|
271
|
+
"rationale_summary": {"type": "string", "minLength": 1},
|
|
272
|
+
"steps": {
|
|
273
|
+
"type": "array",
|
|
274
|
+
"items": _plan_step_schema(),
|
|
275
|
+
"minItems": 1,
|
|
276
|
+
},
|
|
277
|
+
},
|
|
278
|
+
"required": ["rationale_summary", "steps"],
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
def _repair_schema() -> dict[str, Any]:
|
|
283
|
+
return {
|
|
284
|
+
"type": "object",
|
|
285
|
+
"additionalProperties": False,
|
|
286
|
+
"properties": {
|
|
287
|
+
"failure_summary": {"type": "string", "minLength": 1},
|
|
288
|
+
"steps": {
|
|
289
|
+
"type": "array",
|
|
290
|
+
"items": _plan_step_schema(),
|
|
291
|
+
"minItems": 1,
|
|
292
|
+
},
|
|
293
|
+
},
|
|
294
|
+
"required": ["failure_summary", "steps"],
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
def _agent_schema() -> dict[str, Any]:
|
|
299
|
+
return {
|
|
300
|
+
"type": "object",
|
|
301
|
+
"additionalProperties": False,
|
|
302
|
+
"properties": {
|
|
303
|
+
"kind": {
|
|
304
|
+
"type": "string",
|
|
305
|
+
"enum": ["TOOL_ACTION", "CONTINUE", "TASK_READY"],
|
|
306
|
+
},
|
|
307
|
+
"summary": {"type": "string", "minLength": 1},
|
|
308
|
+
"action": {
|
|
309
|
+
"type": ["object", "null"],
|
|
310
|
+
"additionalProperties": False,
|
|
311
|
+
"properties": {
|
|
312
|
+
"tool_name": {"type": "string", "minLength": 1},
|
|
313
|
+
"arguments": {
|
|
314
|
+
"type": "object",
|
|
315
|
+
"additionalProperties": True,
|
|
316
|
+
},
|
|
317
|
+
},
|
|
318
|
+
"required": ["tool_name", "arguments"],
|
|
319
|
+
},
|
|
320
|
+
},
|
|
321
|
+
"required": ["kind", "summary", "action"],
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
def _skill_selection_schema() -> dict[str, Any]:
|
|
326
|
+
return {
|
|
327
|
+
"type": "object",
|
|
328
|
+
"additionalProperties": False,
|
|
329
|
+
"properties": {
|
|
330
|
+
"selected_skill_ids": {
|
|
331
|
+
"type": "array",
|
|
332
|
+
"items": {
|
|
333
|
+
"type": "string",
|
|
334
|
+
"pattern": r"^[a-z][a-z0-9-]{0,63}$",
|
|
335
|
+
},
|
|
336
|
+
"maxItems": 2,
|
|
337
|
+
},
|
|
338
|
+
"selection_reason_summary": {
|
|
339
|
+
"type": "string",
|
|
340
|
+
"minLength": 1,
|
|
341
|
+
"maxLength": 1000,
|
|
342
|
+
},
|
|
343
|
+
},
|
|
344
|
+
"required": ["selected_skill_ids", "selection_reason_summary"],
|
|
345
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
"""Concrete Day 8 tracing adapters assembled only by the Composition Root."""
|
|
2
|
+
|
|
3
|
+
from nexus.infrastructure.observability.console import ConsoleTracer
|
|
4
|
+
from nexus.infrastructure.observability.langsmith import LangSmithTracer
|
|
5
|
+
from nexus.infrastructure.observability.structured_logger import StructuredLogger
|
|
6
|
+
|
|
7
|
+
__all__ = ["ConsoleTracer", "LangSmithTracer", "StructuredLogger"]
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
"""Safe JSON Lines tracer for explicit local observability."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import TextIO
|
|
6
|
+
|
|
7
|
+
from nexus.domain.observability import TelemetryEvent, TraceRunFinish, TraceRunStart
|
|
8
|
+
from nexus.infrastructure.observability.structured_logger import StructuredLogger
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class ConsoleTracer:
|
|
12
|
+
"""Write only already-redacted TelemetryEvent values to stderr."""
|
|
13
|
+
|
|
14
|
+
def __init__(
|
|
15
|
+
self,
|
|
16
|
+
logger: StructuredLogger | None = None,
|
|
17
|
+
*,
|
|
18
|
+
stream: TextIO | None = None,
|
|
19
|
+
) -> None:
|
|
20
|
+
if logger is not None and stream is not None:
|
|
21
|
+
raise ValueError("Provide a StructuredLogger or stream, not both.")
|
|
22
|
+
self._logger = logger or StructuredLogger(stream)
|
|
23
|
+
|
|
24
|
+
async def start_run(self, start: TraceRunStart) -> None:
|
|
25
|
+
return None
|
|
26
|
+
|
|
27
|
+
async def record(self, event: TelemetryEvent) -> None:
|
|
28
|
+
await self._logger.record(event)
|
|
29
|
+
|
|
30
|
+
async def finish(self, finish: TraceRunFinish) -> None:
|
|
31
|
+
await self._logger.flush()
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
"""Manual sanitized mapping from Nexus telemetry to the LangSmith client API."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
from datetime import datetime
|
|
7
|
+
from typing import Any, Protocol
|
|
8
|
+
from uuid import UUID
|
|
9
|
+
|
|
10
|
+
from nexus.domain.observability import (
|
|
11
|
+
TelemetryEvent,
|
|
12
|
+
TelemetryEventType,
|
|
13
|
+
TraceRunFinish,
|
|
14
|
+
TraceRunStart,
|
|
15
|
+
telemetry_payload_dict,
|
|
16
|
+
)
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class LangSmithClient(Protocol):
|
|
20
|
+
def create_run(
|
|
21
|
+
self, name: str, inputs: dict[str, Any], run_type: str, **kwargs: Any
|
|
22
|
+
) -> None: ...
|
|
23
|
+
|
|
24
|
+
def update_run(self, run_id: object, **kwargs: Any) -> None: ...
|
|
25
|
+
|
|
26
|
+
def flush(self, timeout: float | None = None) -> None: ...
|
|
27
|
+
|
|
28
|
+
def close(self, timeout: float | None = None) -> None: ...
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class LangSmithTracer:
|
|
32
|
+
"""Expose no provider objects and submit only pre-redacted safe values."""
|
|
33
|
+
|
|
34
|
+
def __init__(
|
|
35
|
+
self,
|
|
36
|
+
client: LangSmithClient,
|
|
37
|
+
*,
|
|
38
|
+
project: str,
|
|
39
|
+
flush_timeout_seconds: float = 2.0,
|
|
40
|
+
) -> None:
|
|
41
|
+
self._client = client
|
|
42
|
+
self._project = project
|
|
43
|
+
self._flush_timeout_seconds = flush_timeout_seconds
|
|
44
|
+
self._root_events: dict[str, list[dict[str, object]]] = {}
|
|
45
|
+
self._dotted_orders: dict[str, dict[str, str]] = {}
|
|
46
|
+
self._parent_ids: dict[str, dict[str, str]] = {}
|
|
47
|
+
|
|
48
|
+
async def start_run(self, start: TraceRunStart) -> None:
|
|
49
|
+
context = start.context
|
|
50
|
+
root_id = UUID(context.execution_id)
|
|
51
|
+
root_dotted_order = _dotted_segment(context.started_at, root_id)
|
|
52
|
+
self._root_events[context.execution_id] = []
|
|
53
|
+
self._dotted_orders[context.execution_id] = {
|
|
54
|
+
context.execution_id: root_dotted_order
|
|
55
|
+
}
|
|
56
|
+
self._parent_ids[context.execution_id] = {}
|
|
57
|
+
await asyncio.to_thread(
|
|
58
|
+
self._client.create_run,
|
|
59
|
+
"nexus.run",
|
|
60
|
+
{},
|
|
61
|
+
"chain",
|
|
62
|
+
id=root_id,
|
|
63
|
+
trace_id=root_id,
|
|
64
|
+
dotted_order=root_dotted_order,
|
|
65
|
+
project_name=self._project,
|
|
66
|
+
start_time=context.started_at,
|
|
67
|
+
outputs={},
|
|
68
|
+
extra={
|
|
69
|
+
"metadata": {
|
|
70
|
+
"nexus.schema_version": "1.0",
|
|
71
|
+
"nexus.trace_id": context.trace_id,
|
|
72
|
+
"nexus.execution_id": context.execution_id,
|
|
73
|
+
"nexus.run_id": context.run_id,
|
|
74
|
+
"nexus.session_id": context.session_id,
|
|
75
|
+
"nexus.is_resume": context.is_resume,
|
|
76
|
+
"task_character_count": start.task_character_count,
|
|
77
|
+
"model_provider": start.model_provider,
|
|
78
|
+
"model_name": start.model_name,
|
|
79
|
+
}
|
|
80
|
+
},
|
|
81
|
+
tags=["nexus", "schema:1.0"],
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
async def record(self, event: TelemetryEvent) -> None:
|
|
85
|
+
if event.event_type in _SPAN_START_TYPES:
|
|
86
|
+
await self._create_span(event)
|
|
87
|
+
return
|
|
88
|
+
if event.event_type in _SPAN_FINISH_TYPES:
|
|
89
|
+
await self._finish_span(event)
|
|
90
|
+
return
|
|
91
|
+
root_events = self._root_events.setdefault(event.execution_id, [])
|
|
92
|
+
root_events.append(
|
|
93
|
+
{
|
|
94
|
+
"name": event.event_type.value,
|
|
95
|
+
"time": event.timestamp.isoformat(),
|
|
96
|
+
"kwargs": telemetry_payload_dict(event.payload),
|
|
97
|
+
}
|
|
98
|
+
)
|
|
99
|
+
await asyncio.to_thread(
|
|
100
|
+
self._client.update_run,
|
|
101
|
+
UUID(event.execution_id),
|
|
102
|
+
events=list(root_events),
|
|
103
|
+
**self._run_reference(event.execution_id, event.execution_id),
|
|
104
|
+
)
|
|
105
|
+
|
|
106
|
+
async def finish(self, finish: TraceRunFinish) -> None:
|
|
107
|
+
context = finish.context
|
|
108
|
+
output = {
|
|
109
|
+
"execution_outcome": finish.execution_outcome.value,
|
|
110
|
+
"runtime_status": finish.runtime_status.value,
|
|
111
|
+
"terminal_status": (
|
|
112
|
+
None if finish.terminal_status is None else finish.terminal_status.value
|
|
113
|
+
),
|
|
114
|
+
"duration_ms": finish.duration_ms,
|
|
115
|
+
"step_count": finish.step_count,
|
|
116
|
+
"llm_call_count": finish.llm_call_count,
|
|
117
|
+
"tool_call_count": finish.tool_call_count,
|
|
118
|
+
"replan_count": finish.replan_count,
|
|
119
|
+
"repair_count": finish.repair_count,
|
|
120
|
+
"token_usage": {
|
|
121
|
+
"input_tokens": finish.token_usage.input_tokens,
|
|
122
|
+
"output_tokens": finish.token_usage.output_tokens,
|
|
123
|
+
"total_tokens": finish.token_usage.total_tokens,
|
|
124
|
+
"availability": finish.token_usage.availability.value,
|
|
125
|
+
},
|
|
126
|
+
"changed_file_count": finish.changed_file_count,
|
|
127
|
+
"validation_status": finish.validation_status.value,
|
|
128
|
+
"error_code": finish.error_code,
|
|
129
|
+
}
|
|
130
|
+
await asyncio.to_thread(
|
|
131
|
+
self._client.update_run,
|
|
132
|
+
UUID(context.execution_id),
|
|
133
|
+
end_time=finish.finished_at,
|
|
134
|
+
outputs=output,
|
|
135
|
+
error=finish.error_code,
|
|
136
|
+
**self._run_reference(context.execution_id, context.execution_id),
|
|
137
|
+
)
|
|
138
|
+
await asyncio.to_thread(self._client.flush, self._flush_timeout_seconds)
|
|
139
|
+
self._root_events.pop(context.execution_id, None)
|
|
140
|
+
self._dotted_orders.pop(context.execution_id, None)
|
|
141
|
+
self._parent_ids.pop(context.execution_id, None)
|
|
142
|
+
|
|
143
|
+
async def close(self) -> None:
|
|
144
|
+
await asyncio.to_thread(self._client.flush, self._flush_timeout_seconds)
|
|
145
|
+
await asyncio.to_thread(self._client.close, self._flush_timeout_seconds)
|
|
146
|
+
|
|
147
|
+
async def _create_span(self, event: TelemetryEvent) -> None:
|
|
148
|
+
if event.span_id is None:
|
|
149
|
+
return
|
|
150
|
+
run_type, name = _span_identity(event)
|
|
151
|
+
span_id = UUID(event.span_id)
|
|
152
|
+
parent_id = event.parent_span_id or event.execution_id
|
|
153
|
+
orders = self._dotted_orders.setdefault(event.execution_id, {})
|
|
154
|
+
parent_dotted_order = orders.get(parent_id)
|
|
155
|
+
if parent_dotted_order is None:
|
|
156
|
+
return
|
|
157
|
+
dotted_order = f"{parent_dotted_order}.{_dotted_segment(event.timestamp, span_id)}"
|
|
158
|
+
orders[event.span_id] = dotted_order
|
|
159
|
+
self._parent_ids.setdefault(event.execution_id, {})[event.span_id] = parent_id
|
|
160
|
+
await asyncio.to_thread(
|
|
161
|
+
self._client.create_run,
|
|
162
|
+
name,
|
|
163
|
+
{},
|
|
164
|
+
run_type,
|
|
165
|
+
id=span_id,
|
|
166
|
+
trace_id=UUID(event.execution_id),
|
|
167
|
+
# Use the SDK's documented batched wire form.
|
|
168
|
+
parent_run_id=str(parent_id),
|
|
169
|
+
dotted_order=dotted_order,
|
|
170
|
+
project_name=self._project,
|
|
171
|
+
start_time=event.timestamp,
|
|
172
|
+
outputs={},
|
|
173
|
+
extra={"metadata": telemetry_payload_dict(event.payload)},
|
|
174
|
+
tags=[f"phase:{event.phase.value}", "schema:1.0"],
|
|
175
|
+
)
|
|
176
|
+
|
|
177
|
+
async def _finish_span(self, event: TelemetryEvent) -> None:
|
|
178
|
+
if event.span_id is None:
|
|
179
|
+
return
|
|
180
|
+
payload = telemetry_payload_dict(event.payload)
|
|
181
|
+
error_code = payload.get("error_code")
|
|
182
|
+
await asyncio.to_thread(
|
|
183
|
+
self._client.update_run,
|
|
184
|
+
UUID(event.span_id),
|
|
185
|
+
end_time=event.timestamp,
|
|
186
|
+
outputs=payload,
|
|
187
|
+
error=error_code if isinstance(error_code, str) else None,
|
|
188
|
+
**self._run_reference(event.execution_id, event.span_id),
|
|
189
|
+
)
|
|
190
|
+
|
|
191
|
+
def _run_reference(self, execution_id: str, span_id: str) -> dict[str, object]:
|
|
192
|
+
dotted_order = self._dotted_orders.get(execution_id, {}).get(span_id)
|
|
193
|
+
if dotted_order is None:
|
|
194
|
+
return {}
|
|
195
|
+
reference: dict[str, object] = {
|
|
196
|
+
"trace_id": UUID(execution_id),
|
|
197
|
+
"dotted_order": dotted_order,
|
|
198
|
+
}
|
|
199
|
+
parent_id = self._parent_ids.get(execution_id, {}).get(span_id)
|
|
200
|
+
if parent_id is not None:
|
|
201
|
+
# A separate batched update is validated independently from create,
|
|
202
|
+
# so it must retain the child relationship as well.
|
|
203
|
+
reference["parent_run_id"] = parent_id
|
|
204
|
+
return reference
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
_SPAN_START_TYPES: frozenset[TelemetryEventType] = frozenset(
|
|
208
|
+
{
|
|
209
|
+
TelemetryEventType.MODEL_CALL_STARTED,
|
|
210
|
+
TelemetryEventType.TOOL_STARTED,
|
|
211
|
+
TelemetryEventType.VALIDATION_STARTED,
|
|
212
|
+
}
|
|
213
|
+
)
|
|
214
|
+
_SPAN_FINISH_TYPES: frozenset[TelemetryEventType] = frozenset(
|
|
215
|
+
{
|
|
216
|
+
TelemetryEventType.MODEL_CALL_FINISHED,
|
|
217
|
+
TelemetryEventType.TOOL_FINISHED,
|
|
218
|
+
TelemetryEventType.VALIDATION_FINISHED,
|
|
219
|
+
}
|
|
220
|
+
)
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def _span_identity(event: TelemetryEvent) -> tuple[str, str]:
|
|
224
|
+
if event.event_type is TelemetryEventType.MODEL_CALL_STARTED:
|
|
225
|
+
return "llm", "nexus.model"
|
|
226
|
+
if event.event_type is TelemetryEventType.TOOL_STARTED:
|
|
227
|
+
tool_name = event.payload.get("tool_name")
|
|
228
|
+
safe_name = tool_name if isinstance(tool_name, str) else "unknown"
|
|
229
|
+
return "tool", f"nexus.tool.{safe_name}"
|
|
230
|
+
return "chain", "nexus.validation"
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
def _dotted_segment(timestamp: datetime, run_id: UUID) -> str:
|
|
234
|
+
"""Build the provider hierarchy segment without importing LangSmith internals."""
|
|
235
|
+
|
|
236
|
+
return timestamp.strftime("%Y%m%dT%H%M%S%fZ") + str(run_id)
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
"""Sink-only structured JSON Lines logger for already-redacted telemetry."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import json
|
|
7
|
+
import sys
|
|
8
|
+
from typing import TextIO
|
|
9
|
+
|
|
10
|
+
from nexus.domain.observability import (
|
|
11
|
+
TelemetryEvent,
|
|
12
|
+
TelemetrySeverity,
|
|
13
|
+
telemetry_payload_dict,
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
_LEVELS = {
|
|
17
|
+
TelemetrySeverity.DEBUG: 10,
|
|
18
|
+
TelemetrySeverity.INFO: 20,
|
|
19
|
+
TelemetrySeverity.WARNING: 30,
|
|
20
|
+
TelemetrySeverity.ERROR: 40,
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class StructuredLogger:
|
|
25
|
+
"""Serialize only TelemetryEvent values and write one complete UTF-8 JSON line."""
|
|
26
|
+
|
|
27
|
+
def __init__(self, stream: TextIO | None = None) -> None:
|
|
28
|
+
self._stream = stream or sys.stderr
|
|
29
|
+
self._lock = asyncio.Lock()
|
|
30
|
+
|
|
31
|
+
async def record(self, event: TelemetryEvent) -> None:
|
|
32
|
+
level = _LEVELS[event.severity]
|
|
33
|
+
line = json.dumps(
|
|
34
|
+
_event_dict(event), ensure_ascii=False, separators=(",", ":")
|
|
35
|
+
)
|
|
36
|
+
async with self._lock:
|
|
37
|
+
await asyncio.to_thread(self._write, level, line)
|
|
38
|
+
|
|
39
|
+
async def flush(self) -> None:
|
|
40
|
+
async with self._lock:
|
|
41
|
+
await asyncio.to_thread(self._stream.flush)
|
|
42
|
+
|
|
43
|
+
def _write(self, level: int, line: str) -> None:
|
|
44
|
+
del level # Level selection is deliberately derived only from TelemetrySeverity.
|
|
45
|
+
self._stream.write(f"{line}\n")
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _event_dict(event: TelemetryEvent) -> dict[str, object]:
|
|
49
|
+
return {
|
|
50
|
+
"schema_version": event.schema_version,
|
|
51
|
+
"event_id": event.event_id,
|
|
52
|
+
"event_type": event.event_type.value,
|
|
53
|
+
"timestamp": event.timestamp.isoformat(),
|
|
54
|
+
"sequence": event.sequence,
|
|
55
|
+
"trace_id": event.trace_id,
|
|
56
|
+
"execution_id": event.execution_id,
|
|
57
|
+
"run_id": event.run_id,
|
|
58
|
+
"session_id": event.session_id,
|
|
59
|
+
"span_id": event.span_id,
|
|
60
|
+
"parent_span_id": event.parent_span_id,
|
|
61
|
+
"phase": event.phase.value,
|
|
62
|
+
"severity": event.severity.value,
|
|
63
|
+
"payload": telemetry_payload_dict(event.payload),
|
|
64
|
+
"redaction": {
|
|
65
|
+
"policy_version": event.redaction.policy_version,
|
|
66
|
+
"redacted": event.redaction.redacted,
|
|
67
|
+
"omitted_fields": list(event.redaction.omitted_fields),
|
|
68
|
+
"truncated_fields": list(event.redaction.truncated_fields),
|
|
69
|
+
},
|
|
70
|
+
}
|