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.
Files changed (131) hide show
  1. nexus/__init__.py +4 -0
  2. nexus/application/__init__.py +2 -0
  3. nexus/application/approval_service.py +130 -0
  4. nexus/application/diff_service.py +177 -0
  5. nexus/application/event_publisher.py +180 -0
  6. nexus/application/execution_context.py +29 -0
  7. nexus/application/execution_ledger.py +126 -0
  8. nexus/application/model_call_context.py +29 -0
  9. nexus/application/observed_model_gateway.py +194 -0
  10. nexus/application/plan_approval_service.py +250 -0
  11. nexus/application/planning.py +668 -0
  12. nexus/application/runtime.py +624 -0
  13. nexus/application/session_service.py +411 -0
  14. nexus/application/structured_output.py +96 -0
  15. nexus/application/telemetry.py +396 -0
  16. nexus/application/telemetry_subscriber.py +216 -0
  17. nexus/application/tool_runtime.py +496 -0
  18. nexus/application/tracing_dispatcher.py +283 -0
  19. nexus/application/validation.py +293 -0
  20. nexus/config/__init__.py +17 -0
  21. nexus/config/loader.py +253 -0
  22. nexus/config/models.py +310 -0
  23. nexus/context/__init__.py +6 -0
  24. nexus/context/budget.py +24 -0
  25. nexus/context/builder.py +92 -0
  26. nexus/context/chunking.py +65 -0
  27. nexus/context/explorer.py +246 -0
  28. nexus/context/integration.py +63 -0
  29. nexus/context/manager.py +328 -0
  30. nexus/context/retrieval.py +261 -0
  31. nexus/domain/__init__.py +2 -0
  32. nexus/domain/agent_decision.py +113 -0
  33. nexus/domain/agent_state.py +49 -0
  34. nexus/domain/approvals.py +64 -0
  35. nexus/domain/context.py +108 -0
  36. nexus/domain/exploration.py +86 -0
  37. nexus/domain/mcp.py +51 -0
  38. nexus/domain/model.py +173 -0
  39. nexus/domain/observability.py +326 -0
  40. nexus/domain/persistence.py +122 -0
  41. nexus/domain/planning.py +329 -0
  42. nexus/domain/ports/__init__.py +61 -0
  43. nexus/domain/ports/agent_decision.py +9 -0
  44. nexus/domain/ports/approval_unit_of_work.py +27 -0
  45. nexus/domain/ports/checkpoint_provider.py +11 -0
  46. nexus/domain/ports/context.py +71 -0
  47. nexus/domain/ports/events.py +21 -0
  48. nexus/domain/ports/graph_runtime.py +30 -0
  49. nexus/domain/ports/mcp.py +23 -0
  50. nexus/domain/ports/model_gateway.py +21 -0
  51. nexus/domain/ports/model_input_budget.py +15 -0
  52. nexus/domain/ports/planning.py +62 -0
  53. nexus/domain/ports/repositories.py +54 -0
  54. nexus/domain/ports/repository_context.py +18 -0
  55. nexus/domain/ports/session_unit_of_work.py +33 -0
  56. nexus/domain/ports/skills.py +41 -0
  57. nexus/domain/ports/tooling.py +39 -0
  58. nexus/domain/ports/tracer.py +13 -0
  59. nexus/domain/ports/validation.py +32 -0
  60. nexus/domain/runtime_events.py +445 -0
  61. nexus/domain/skills.py +129 -0
  62. nexus/domain/tooling.py +163 -0
  63. nexus/domain/validation.py +161 -0
  64. nexus/errors/__init__.py +82 -0
  65. nexus/evaluation/__init__.py +7 -0
  66. nexus/evaluation/assertions.py +4 -0
  67. nexus/evaluation/evaluator.py +263 -0
  68. nexus/evaluation/fixtures.py +36 -0
  69. nexus/evaluation/harness.py +606 -0
  70. nexus/evaluation/loader.py +415 -0
  71. nexus/evaluation/metrics.py +27 -0
  72. nexus/evaluation/models.py +362 -0
  73. nexus/evaluation/report.py +43 -0
  74. nexus/evaluation/runner.py +480 -0
  75. nexus/infrastructure/__init__.py +2 -0
  76. nexus/infrastructure/asyncio_compat.py +13 -0
  77. nexus/infrastructure/bootstrap/__init__.py +17 -0
  78. nexus/infrastructure/bootstrap/composition.py +663 -0
  79. nexus/infrastructure/checkpoint/__init__.py +5 -0
  80. nexus/infrastructure/checkpoint/postgres.py +62 -0
  81. nexus/infrastructure/database.py +39 -0
  82. nexus/infrastructure/embedding.py +61 -0
  83. nexus/infrastructure/graph/__init__.py +6 -0
  84. nexus/infrastructure/graph/day4_runtime.py +966 -0
  85. nexus/infrastructure/graph/langgraph_runtime.py +172 -0
  86. nexus/infrastructure/mcp/__init__.py +5 -0
  87. nexus/infrastructure/mcp/manager.py +380 -0
  88. nexus/infrastructure/model_gateway/__init__.py +6 -0
  89. nexus/infrastructure/model_gateway/openai_compatible.py +345 -0
  90. nexus/infrastructure/observability/__init__.py +7 -0
  91. nexus/infrastructure/observability/console.py +31 -0
  92. nexus/infrastructure/observability/langsmith.py +236 -0
  93. nexus/infrastructure/observability/structured_logger.py +70 -0
  94. nexus/infrastructure/persistence/__init__.py +13 -0
  95. nexus/infrastructure/persistence/approval_unit_of_work.py +74 -0
  96. nexus/infrastructure/persistence/models.py +146 -0
  97. nexus/infrastructure/persistence/repositories.py +326 -0
  98. nexus/infrastructure/persistence/unit_of_work.py +82 -0
  99. nexus/infrastructure/repository_files.py +117 -0
  100. nexus/infrastructure/sandbox/__init__.py +5 -0
  101. nexus/infrastructure/sandbox/local_process.py +353 -0
  102. nexus/infrastructure/semantic.py +276 -0
  103. nexus/infrastructure/semantic_models.py +56 -0
  104. nexus/interfaces/__init__.py +2 -0
  105. nexus/interfaces/cli/__init__.py +2 -0
  106. nexus/interfaces/cli/__main__.py +6 -0
  107. nexus/interfaces/cli/app.py +266 -0
  108. nexus/interfaces/cli/renderer.py +118 -0
  109. nexus/security/__init__.py +14 -0
  110. nexus/security/approval_policies.py +73 -0
  111. nexus/security/command_policy.py +117 -0
  112. nexus/security/executables.py +107 -0
  113. nexus/security/git_commands.py +65 -0
  114. nexus/security/workspace.py +93 -0
  115. nexus/skills/__init__.py +7 -0
  116. nexus/skills/builtin/__init__.py +1 -0
  117. nexus/skills/builtin/debug-python/SKILL.md +26 -0
  118. nexus/skills/builtin/review-repository/SKILL.md +26 -0
  119. nexus/skills/builtin/write-tests/SKILL.md +26 -0
  120. nexus/skills/loader.py +439 -0
  121. nexus/skills/registry.py +146 -0
  122. nexus/skills/selector.py +152 -0
  123. nexus/tools/__init__.py +6 -0
  124. nexus/tools/editing.py +312 -0
  125. nexus/tools/mcp.py +160 -0
  126. nexus/tools/native.py +654 -0
  127. nexus/tools/registry.py +27 -0
  128. nexus_coding_agent-0.1.0.dist-info/METADATA +142 -0
  129. nexus_coding_agent-0.1.0.dist-info/RECORD +131 -0
  130. nexus_coding_agent-0.1.0.dist-info/WHEEL +4 -0
  131. 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
+ }