hermes-trace/hooks.py

415 lines
16 KiB
Python

from __future__ import annotations
import json
import logging
import time
from collections.abc import Mapping
from typing import Any
from . import _state, db
logger = logging.getLogger(__name__)
def on_pre_api_request(
*,
session_id: str,
turn_id: str = "",
task_id: str = "",
api_request_id: str = "",
request_messages: list[dict[str, Any]],
request: dict[str, Any] | None = None,
conversation_history: list[dict[str, Any]] | None = None,
system_prompt: Any = None,
api_mode: str = "",
**_: Any,
) -> None:
"""Capture request preview *before* the LLM API call is made.
The preview is stored in ``_session_state`` and consumed by
:func:`on_post_api_request`.
"""
try:
key = _state._state_key(
session_id, turn_id=turn_id, task_id=task_id, api_request_id=api_request_id
)
request_preview = ""
full_request = ""
# Convert Codex input items to standard messages if needed
standard_msgs: list[dict[str, Any]] | None = None
if api_mode == "anthropic_messages":
# Third-party Anthropic-compatible transports (for example MiniMax)
# may strip historical thinking blocks from the provider-bound
# messages. Hermes' canonical conversation_history still retains
# reasoning/reasoning_content/reasoning_details, so use it for the
# human-readable Full Request transcript when available.
if conversation_history:
standard_msgs = _state._convert_hermes_history_to_standard_messages(
conversation_history
)
else:
standard_msgs = _state._convert_anthropic_messages_to_standard_messages(
request_messages
)
elif request_messages and any(
isinstance(m, dict) and "type" in m for m in request_messages
):
standard_msgs = _state._convert_codex_input_to_standard_messages(
request_messages
)
# Find the last message whose role is not "system"
for msg in reversed(request_messages):
content = msg.get("content", "") or ""
role = msg.get("role", "")
if role != "system" and content:
request_preview = _state._preview_text(content)[:300]
break
# Build the normalized request transcript. Hermes passes the provider-bound
# system prompt separately because Responses and Anthropic keep it outside
# their message arrays.
if standard_msgs is not None:
base_msgs: list[dict[str, Any]] = standard_msgs
else:
base_msgs = (
list(request_messages) if isinstance(request_messages, list) else []
)
# Inject system prompt if not already present
if not any(m.get("role") == "system" for m in base_msgs):
system_content: Any = None
if system_prompt is not None:
system_content = _state._preview_text(system_prompt) or None
if not system_content and conversation_history:
for msg in conversation_history:
if msg.get("role") == "system":
system_content = msg.get("content") or None
break
if not system_content and request:
body = request.get("body", {}) or {}
system_content = body.get("instructions") or None
if not system_content and session_id:
system_content = _state._get_system_prompt_from_state_db(session_id)
if system_content:
base_msgs.insert(0, {"role": "system", "content": system_content})
full_request = json.dumps(base_msgs, ensure_ascii=False, default=str)
_state._evict_stale_state()
with _state._STATE_LOCK:
state = _state._session_state.setdefault(key, {})
state["session_id"] = session_id
state["_created_at"] = time.monotonic()
state["task_id"] = task_id
state["turn_id"] = turn_id
state["api_request_id"] = api_request_id
state["request_preview"] = request_preview
state["full_request"] = full_request
except Exception:
logger.exception("on_pre_api_request — failed to capture request preview")
def on_post_api_request(
*,
session_id: str,
task_id: str = "",
turn_id: str = "",
api_request_id: str = "",
model: str,
usage: dict[str, Any],
api_duration: float | None,
finish_reason: str,
assistant_message: Any,
assistant_tool_call_count: int,
api_call_count: int,
response: dict[str, Any],
**_: Any,
) -> None:
"""Write the completed API call turn into the telemetry database."""
try:
key = _state._state_key(
session_id, turn_id=turn_id, task_id=task_id, api_request_id=api_request_id
)
with _state._STATE_LOCK:
state = _state._session_state.get(key, {})
request_preview: str = state.get("request_preview", "") or ""
full_request: str = state.get("full_request", "") or ""
provider: str | None = _.get("provider")
# -- Token usage (keys may differ by provider) ------------------------
usage = usage or {}
input_tokens: int | None = usage.get("input_tokens")
if input_tokens is None:
input_tokens = usage.get("prompt_tokens")
output_tokens: int | None = usage.get("output_tokens")
if output_tokens is None:
output_tokens = usage.get("completion_tokens")
total_tokens: int | None = usage.get("total_tokens")
cache_read_tokens: int | None = usage.get("cache_read_tokens")
cache_write_tokens: int | None = usage.get("cache_write_tokens")
reasoning_tokens: int | None = usage.get("reasoning_tokens")
# -- Response and reasoning -------------------------------------------
# Hermes' Responses adapter folds user-visible commentary message items
# into assistant_message.reasoning. The preserved Codex sidecars retain
# the original semantics, so classify them before writing telemetry.
codex_message_items = getattr(assistant_message, "codex_message_items", None)
codex_reasoning_items = getattr(
assistant_message, "codex_reasoning_items", None
)
if codex_message_items or codex_reasoning_items:
response_parts: list[str] = []
if isinstance(codex_message_items, list):
for item in codex_message_items:
if not isinstance(item, Mapping) or item.get("type") != "message":
continue
text = _state._preview_text(item.get("content"))
if text:
response_parts.append(text)
response_preview = "\n\n".join(response_parts)
if not response_preview:
response_preview = _state._preview_text(
getattr(assistant_message, "content", "")
)
reasoning_parts: list[str] = []
if isinstance(codex_reasoning_items, list):
for item in codex_reasoning_items:
if not isinstance(item, dict) or item.get("type") != "reasoning":
continue
text = _state._responses_reasoning_summary(item)
if text:
reasoning_parts.append(text)
reasoning = "\n\n".join(reasoning_parts)
else:
raw_content = getattr(assistant_message, "content", "")
response_preview = _state._preview_text(raw_content)
# ``assistant_message.reasoning`` is the canonical field, but many
# providers (DeepSeek V4 Flash, Kimi, etc.) emit it as
# ``reasoning_content`` on the response object, which lands on
# ``assistant_message.reasoning_content`` instead. MiniMax stores it
# under ``provider_data["reasoning_content"]``.
raw_reasoning = getattr(assistant_message, "reasoning", None)
if not raw_reasoning:
provider_data = getattr(assistant_message, "provider_data", None)
if isinstance(provider_data, Mapping):
raw_reasoning = provider_data.get("reasoning_content")
if not raw_reasoning:
raw_reasoning = getattr(assistant_message, "reasoning_content", None)
if not raw_reasoning:
reasoning_details = getattr(
assistant_message, "reasoning_details", None
)
if not reasoning_details:
provider_data = getattr(assistant_message, "provider_data", None)
if isinstance(provider_data, Mapping):
reasoning_details = provider_data.get("reasoning_details")
if isinstance(reasoning_details, list):
thinking_parts = [
detail.get("thinking")
for detail in reasoning_details
if isinstance(detail, Mapping)
and detail.get("type") == "thinking"
and isinstance(detail.get("thinking"), str)
and detail.get("thinking")
]
if thinking_parts:
raw_reasoning = "\n\n".join(thinking_parts)
reasoning = str(raw_reasoning) if raw_reasoning is not None else ""
# -- Duration ---------------------------------------------------------
elapsed_ms: int | None = (
int(api_duration * 1000) if api_duration is not None else None
)
# -- Full response payload --------------------------------------------
response_view = dict(response)
response_assistant = response_view.get("assistant_message")
if isinstance(response_assistant, Mapping):
response_assistant = dict(response_assistant)
if codex_message_items or codex_reasoning_items:
response_assistant["content"] = response_preview
if reasoning:
response_assistant["reasoning_content"] = reasoning
else:
response_assistant.pop("reasoning_content", None)
elif reasoning:
response_assistant.setdefault("reasoning_content", reasoning)
response_view["assistant_message"] = response_assistant
full_response: str = json.dumps(response_view, ensure_ascii=False, default=str)
# -- Write turn -------------------------------------------------------
db_turn_id = db.get_db().write_turn(
session_id=session_id,
model=model,
provider=provider,
api_call_count=api_call_count,
request_preview=request_preview,
response_preview=response_preview,
reasoning=reasoning,
finish_reason=finish_reason,
input_tokens=input_tokens,
output_tokens=output_tokens,
total_tokens=total_tokens,
cache_read_tokens=cache_read_tokens,
cache_write_tokens=cache_write_tokens,
reasoning_tokens=reasoning_tokens,
elapsed_ms=elapsed_ms,
tool_calls_count=assistant_tool_call_count,
full_request=full_request,
full_response=full_response,
)
# -- Update session state ---------------------------------------------
with _state._STATE_LOCK:
if assistant_tool_call_count == 0:
# No tool calls expected — clean up immediately
_state._session_state.pop(key, None)
else:
state = _state._session_state.setdefault(key, {})
state["session_id"] = session_id
state["task_id"] = task_id
state["turn_id"] = turn_id
state["api_request_id"] = api_request_id
state["latest_turn_id"] = db_turn_id
state["tool_call_counter"] = 0
state["expected_tool_calls"] = assistant_tool_call_count
except Exception:
logger.exception("on_post_api_request — failed to write turn")
def on_api_request_error(
*,
session_id: str,
task_id: str = "",
turn_id: str = "",
api_request_id: str = "",
model: str,
provider: str | None,
api_call_count: int,
api_duration: float | None,
error: dict[str, Any],
**_: Any,
) -> None:
"""Record a failed LLM API call and discard its pending state."""
key = _state._state_key(
session_id, turn_id=turn_id, task_id=task_id, api_request_id=api_request_id
)
try:
error_type = error.get("type", "unknown")
error_message = error.get("message", "")
with _state._STATE_LOCK:
state = _state._session_state.get(key)
if state is None:
logger.warning(
"on_api_request_error — no session state for key %s", key
)
request_preview = ""
else:
request_preview = state.get("request_preview", "") or ""
request = _.get("request")
full_request = (
json.dumps(request, ensure_ascii=False, default=str)
if isinstance(request, dict)
else str(request or "")
)
elapsed_ms = int(api_duration * 1000) if api_duration is not None else None
error_preview = f"{error_type}: {error_message}"[:300]
full_response = json.dumps(
{"error_type": error_type, "error_message": error_message},
ensure_ascii=False,
default=str,
)
db.get_db().write_turn(
session_id=session_id,
model=model,
provider=provider,
api_call_count=api_call_count,
request_preview=request_preview,
response_preview=error_preview,
reasoning="",
finish_reason="error",
input_tokens=None,
output_tokens=None,
total_tokens=None,
cache_read_tokens=None,
cache_write_tokens=None,
reasoning_tokens=None,
elapsed_ms=elapsed_ms,
tool_calls_count=0,
full_request=full_request,
full_response=full_response,
)
except Exception:
logger.exception("on_api_request_error — failed to write turn")
finally:
with _state._STATE_LOCK:
_state._session_state.pop(key, None)
def on_post_tool_call(
*,
session_id: str,
task_id: str = "",
turn_id: str = "",
api_request_id: str = "",
tool_name: str,
args: Any,
result: Any,
duration_ms: int | None,
**_: Any,
) -> None:
"""Write tool call data associated with the most recent turn.
``args`` and ``result`` arrive as dicts from the hook — serialise them
to JSON before writing to SQLite.
"""
try:
key = _state._state_key(
session_id, turn_id=turn_id, task_id=task_id, api_request_id=api_request_id
)
with _state._STATE_LOCK:
state = _state._session_state.get(key)
if state is None:
logger.warning(
"on_post_tool_call — no session state for key %s, skipping", key
)
return
latest_turn_id_raw = state.get("latest_turn_id")
latest_turn_id: int | None = (
latest_turn_id_raw if isinstance(latest_turn_id_raw, int) else None
)
if latest_turn_id is None:
logger.warning(
"on_post_tool_call — no latest_turn_id for key %s, skipping",
key,
)
return
call_order: int = state.get("tool_call_counter", 0)
state["tool_call_counter"] = call_order + 1
expected = state.get("expected_tool_calls", 0)
if expected > 0 and call_order + 1 >= expected:
_state._session_state.pop(key, None)
db.get_db().write_tool_call(
turn_id=latest_turn_id,
call_order=call_order,
name=tool_name,
args=json.dumps(args, ensure_ascii=False, default=str),
result=json.dumps(result, ensure_ascii=False, default=str),
duration_ms=duration_ms,
error=None,
)
except Exception:
logger.exception("on_post_tool_call — failed to write tool call")