From e5c3c7cd790efa21fe846f71badd93dd3e9ea9f0 Mon Sep 17 00:00:00 2001 From: Caleb Fahlgren Date: Mon, 16 Nov 2026 12:44:13 -0500 Subject: [PATCH] add sts session trace format support --- docs/python-api.md | 3 + examples/example_sts_session.jsonl | 9 ++ src/teich/converter.py | 139 ++++++++++++++++++++++++++++- tests/test_converter.py | 102 ++++++++++++++++++++- 4 files changed, 251 insertions(+), 2 deletions(-) create mode 100644 examples/example_sts_session.jsonl diff --git a/docs/python-api.md b/docs/python-api.md index b573e26..5b3a15a 100644 --- a/docs/python-api.md +++ b/docs/python-api.md @@ -132,10 +132,13 @@ Returns one of: - `openclaw` - `hermes` - `external_agent` +- `sts` - `None` Factory `droid` CLI sessions are supported as a conversion-only source. Point `prepare_data()` or `load_traces()` at session JSONL files from `~/.factory/sessions/...`; Teich reads the adjacent `.settings.json` sidecar for model and token usage metadata when present. +Sessions in the Hugging Face [Session Trace Simple Format](https://huggingface.co/docs/hub/session-traces-format) (STS) are supported as a conversion-only source, for example HuggingChat or llama.app exports. The header's `harness` id is kept in `metadata.harness`. + DeepSeek Harness (`dsh`) is also a conversion-only source. `load_traces()` and `prepare_data()` accept native session `.jsonl`, `.jsonl.zstd`, or `.jsonl.zst` files and directories containing them. Parsed native events are detected as `deepseek_harness`; see [DeepSeek Harness data](data-format.md#deepseek-harness). ## Validation Helpers diff --git a/examples/example_sts_session.jsonl b/examples/example_sts_session.jsonl new file mode 100644 index 0000000..8ff4e8c --- /dev/null +++ b/examples/example_sts_session.jsonl @@ -0,0 +1,9 @@ +{"type": "session", "harness": "chat-ui", "id": "6936f1aa0c1d", "name": "Weekend weather in two cities", "chatUi": {"model": "moonshotai/Kimi-K2-Instruct", "exportedAt": "2026-11-14T21:40:00Z"}} +{"type": "message", "message": {"role": "system", "content": "You are HuggingChat, a helpful assistant."}} +{"type": "message", "message": {"role": "user", "content": "Compare the weekend weather in Paris and Lyon.", "timestamp": 1794691865000}} +{"type": "message", "message": {"role": "assistant", "content": "", "model": "moonshotai/Kimi-K2-Instruct", "reasoningContent": "I need forecasts for both cities. I can fetch them in parallel.", "toolCalls": [{"id": "call_paris", "function": {"name": "get_forecast", "arguments": "{\"city\": \"Paris\", \"days\": 2}"}}, {"id": "call_lyon", "function": {"name": "get_forecast", "arguments": "{\"city\": \"Lyon\", \"days\": 2}"}}], "timestamp": 1794691867000}} +{"type": "message", "message": {"role": "tool", "content": "{\"city\": \"Paris\", \"sat\": \"14C rain\", \"sun\": \"16C cloudy\"}", "toolCallId": "call_paris", "timestamp": 1794691868000}} +{"type": "message", "message": {"role": "tool", "content": "{\"city\": \"Lyon\", \"sat\": \"19C sunny\", \"sun\": \"21C sunny\"}", "toolCallId": "call_lyon", "timestamp": 1794691868000}} +{"type": "message", "message": {"role": "assistant", "content": "Lyon wins: sunny, 19\u201321\u00b0C. Paris looks wet on Saturday (14\u00b0C, rain) and cloudy Sunday (16\u00b0C).", "model": "moonshotai/Kimi-K2-Instruct", "timestamp": 1794691870000}} +{"type": "message", "message": {"role": "user", "content": "Should I pack an umbrella for Paris?", "timestamp": 1794691895000}} +{"type": "message", "message": {"role": "assistant", "content": "Yes, Saturday has rain in the forecast.", "model": "moonshotai/Kimi-K2-Instruct", "reasoningContent": "Saturday Paris = rain.", "timestamp": 1794691896000}} diff --git a/src/teich/converter.py b/src/teich/converter.py index d340525..2b39ef6 100644 --- a/src/teich/converter.py +++ b/src/teich/converter.py @@ -26,7 +26,9 @@ PI_SYSTEM_PROMPT_CUSTOM_TYPE = "teich-system-prompt" TEICH_AVAILABLE_TOOLS_CUSTOM_TYPE = "teich-available-tools" TEICH_TRACE_CONTEXT_ITEM_TYPE = "teich_context" -TraceType = Literal["claude_code", "codex", "cursor", "deepseek_harness", "droid", "external_agent", "hermes", "openclaw", "pi"] +TraceType = Literal[ + "claude_code", "codex", "cursor", "deepseek_harness", "droid", "external_agent", "hermes", "openclaw", "pi", "sts" +] _TIMESTAMP_KEYS = ("timestamp", "created_at", "createdAt") _CURSOR_METADATA_KEYS = frozenset( { @@ -1827,6 +1829,28 @@ def _is_openclaw_session_header(event: Any) -> bool: return isinstance(cwd, str) and ".openclaw" in cwd +def _is_sts_session(events: list[Any]) -> bool: + """Session Trace Simple Format: https://huggingface.co/docs/hub/session-traces-format""" + first_event = next((event for event in events if isinstance(event, dict)), None) + if ( + first_event is None + or first_event.get("type") != "session" + or not isinstance(first_event.get("harness"), str) + or not isinstance(first_event.get("id"), str) + ): + return False + # Pi session headers may also carry a `harness` field, but Pi messages hold content blocks or toolResult roles. + messages = [ + event["message"] + for event in events + if isinstance(event, dict) and event.get("type") == "message" and isinstance(event.get("message"), dict) + ] + return bool(messages) and all( + message.get("role") in {"user", "assistant", "system", "tool"} and not isinstance(message.get("content"), list) + for message in messages + ) + + def _external_session_source(event: dict[str, Any]) -> str: payload = event.get("payload") source = payload.get("source") if isinstance(payload, dict) else None @@ -1850,6 +1874,9 @@ def _is_cursor_trace_row(event: Any) -> bool: def _detect_trace_type(events: list[Any], default: TraceType | None = "codex") -> TraceType | None: + # STS headers may carry any extra metadata (cwd, version, ...), so check them before header-only heuristics. + if _is_sts_session(events): + return "sts" if any( _is_deepseek_session_header(event) or isinstance(event, dict) @@ -2850,6 +2877,112 @@ def _convert_droid_trace_to_training_example( ) +def _is_sts_user_message(event: dict[str, Any]) -> bool: + message = event.get("message") + return event.get("type") == "message" and isinstance(message, dict) and message.get("role") == "user" + + +def _convert_sts_trace_to_training_example( + trace_file: Path, + events: list[dict[str, Any]], +) -> TrainingExample: + header = next(event for event in events if isinstance(event, dict)) + messages: list[dict[str, Any]] = [] + tool_names: set[str] = set() + tool_argument_samples: dict[str, list[Any]] = {} + tool_names_by_call_id: dict[str, str] = {} + model: str | None = None + + for event in events: + if not isinstance(event, dict) or event.get("type") != "message": + continue + payload = event.get("message") + if not isinstance(payload, dict): + continue + role = payload.get("role") + raw_content = payload.get("content") + content = raw_content if isinstance(raw_content, str) else "" + + if role == "user": + messages.append({"role": "user", "content": content}) + continue + if role == "system": + if content.strip(): + messages.append({"role": "system", "content": content}) + continue + + if role == "tool": + tool_call_id = payload.get("toolCallId") + if not isinstance(tool_call_id, str) or not tool_call_id: + continue + messages.append( + { + "role": "tool", + "tool_call_id": tool_call_id, + "name": tool_names_by_call_id.get(tool_call_id, "unknown_tool"), + "content": content, + } + ) + continue + + if role != "assistant": + continue + if isinstance(payload.get("model"), str) and payload["model"].strip(): + model = payload["model"].strip() + message: dict[str, Any] = {"role": "assistant", "content": content} + reasoning_content = payload.get("reasoningContent") + if isinstance(reasoning_content, str) and reasoning_content.strip(): + message["reasoning_content"] = reasoning_content + tool_calls: list[dict[str, Any]] = [] + for tool_call in payload.get("toolCalls") or []: + if not isinstance(tool_call, dict) or not isinstance(tool_call.get("function"), dict): + continue + function = tool_call["function"] + tool_call_id = tool_call.get("id") + tool_name = function.get("name") + if not isinstance(tool_call_id, str) or not tool_call_id or not isinstance(tool_name, str) or not tool_name: + continue + arguments = _parse_function_arguments(function.get("arguments")) + if not isinstance(arguments, dict): + # Freeform tools such as Codex's apply_patch export raw text instead of a JSON object. + arguments = _custom_tool_arguments(tool_name, arguments) + tool_names.add(tool_name) + tool_names_by_call_id[tool_call_id] = tool_name + tool_argument_samples.setdefault(tool_name, []).append(arguments) + tool_calls.append( + {"id": tool_call_id, "type": "function", "function": {"name": tool_name, "arguments": arguments}} + ) + if tool_calls: + message["tool_calls"] = tool_calls + if content.strip() or "reasoning_content" in message or tool_calls: + _append_or_merge_assistant_message(messages, message) + + harness = header.get("harness") + title = header.get("name") + cwd = header.get("cwd") + metadata: dict[str, Any] = { + "source_file": trace_file.name, + "session_id": header.get("id") or trace_file.stem, + "trace_type": "sts", + "harness": harness, + "model_provider": None, + "model": model, + "cwd": cwd if isinstance(cwd, str) and cwd.strip() else None, + "title": title if isinstance(title, str) and title.strip() else None, + "turn_count": sum(1 for message in messages if message.get("role") == "user"), + } + _add_first_message_timestamp( + metadata, _first_message_timestamp_from_events(events, _is_sts_user_message) + ) + return TrainingExample( + source_file=trace_file, + prompt=next((message["content"] for message in messages if message["role"] == "user" and message["content"]), ""), + messages=messages, + tools=_build_tools_from_snapshots_and_calls(tool_names, {}, tool_argument_samples), + metadata=metadata, + ) + + def _convert_hermes_trace_to_training_example( trace_file: Path, events: list[dict[str, Any]], @@ -4237,6 +4370,8 @@ def convert_trace_to_training_example(trace_file: Path) -> TrainingExample: example = _convert_deepseek_trace_to_training_example(trace_file, events) elif trace_type == "droid": example = _convert_droid_trace_to_training_example(trace_file, events) + elif trace_type == "sts": + example = _convert_sts_trace_to_training_example(trace_file, events) elif trace_type == "hermes": example = _convert_hermes_trace_to_training_example(trace_file, events) elif trace_type == "cursor": @@ -4299,6 +4434,8 @@ def _convert_jsonl_file_to_training_rows(jsonl_file: Path, *, skip_invalid_lines return [_apply_harness_context_capture(example, rows).to_dict()] if trace_type == "droid": return [_convert_droid_trace_to_training_example(jsonl_file, rows).to_dict()] + if trace_type == "sts": + return [_convert_sts_trace_to_training_example(jsonl_file, rows).to_dict()] if trace_type == "hermes": if all(_is_hermes_trace_row(row) for row in rows): return [ diff --git a/tests/test_converter.py b/tests/test_converter.py index d1950f4..2f0fe0d 100644 --- a/tests/test_converter.py +++ b/tests/test_converter.py @@ -3,7 +3,7 @@ import pytest -from teich import detect_trace_type +from teich import detect_trace_type, validate_tool_calls from teich.converter import ( convert_trace_to_training_example, convert_traces_to_training_data, @@ -26,6 +26,7 @@ def _read_jsonl_events(path: Path) -> list[dict]: ("example_pi_session.jsonl", "pi"), ("example_cursor_session.jsonl", "cursor"), ("example_openclaw_session.jsonl", "openclaw"), + ("example_sts_session.jsonl", "sts"), ], ) def test_detect_trace_type_matches_checked_in_examples(example_file: str, expected_trace_type: str): @@ -76,6 +77,42 @@ def test_detect_trace_type_returns_known_trace_type(): ], "droid", ), + ( + [ + {"type": "session", "harness": "my-agent", "id": "sts-session"}, + {"type": "message", "message": {"role": "user", "content": "hello"}}, + ], + "sts", + ), + ( + [ + {"type": "session", "harness": "my-agent", "id": "s", "cwd": "/home/user/.openclaw/workspace"}, + {"type": "message", "message": {"role": "user", "content": "hello"}}, + ], + "sts", + ), + ( + [ + {"type": "session", "harness": "my-agent", "id": "s", "version": 1, "createdAt": 1794691865000}, + {"type": "message", "message": {"role": "user", "content": "hello"}}, + ], + "sts", + ), + ( + [ + {"type": "session", "harness": "my-agent", "id": "s"}, + {"type": "message", "message": {"role": "user", "content": "hello"}}, + {"type": "message", "message": {"role": "assistant", "content": None, "toolCalls": []}}, + ], + "sts", + ), + ( + [ + {"type": "session", "harness": "my-agent", "id": "pi-session", "version": 3}, + {"type": "message", "message": {"role": "user", "content": [{"type": "text", "text": "hello"}]}}, + ], + "pi", + ), ] for events, expected_trace_type in cases: @@ -1104,6 +1141,69 @@ def test_convert_droid_trace(tmp_path: Path): assert "LS" in tool_names +def test_convert_sts_trace(tmp_path: Path): + trace_file = tmp_path / "sts.jsonl" + events = [ + {"type": "session", "harness": "chat-ui", "id": "sts-session", "name": "What time is it"}, + {"type": "message", "message": {"role": "system", "content": "You are helpful."}}, + {"type": "message", "message": {"role": "user", "content": "what time is it?", "timestamp": 1782918000000}}, + { + "type": "message", + "message": { + "role": "assistant", + "content": "", + "reasoningContent": "I should check the clock.", + "toolCalls": [ + {"id": "t1", "function": {"name": "get_time", "arguments": '{"tz": "UTC"}'}}, + {"id": "t2", "function": {"name": "apply_patch", "arguments": "*** Begin Patch"}}, + ], + "model": "moonshotai/Kimi-K2-Instruct", + }, + }, + {"type": "message", "message": {"role": "tool", "toolCallId": "t1", "content": "2026-07-01T15:00:00Z"}}, + {"type": "message", "message": {"role": "tool", "toolCallId": "t2", "content": "Done!"}}, + {"type": "message", "message": {"role": "assistant", "content": "it is 15:00 UTC"}}, + {"type": "message", "message": {"role": "user", "content": ""}}, + {"type": "message", "message": {"role": "assistant", "content": "anything else?"}}, + ] + trace_file.write_text("\n".join(json.dumps(event) for event in events) + "\n", encoding="utf-8") + + example = convert_trace_to_training_example(trace_file) + + assert example.metadata["trace_type"] == "sts" + assert example.metadata["harness"] == "chat-ui" + assert example.metadata["session_id"] == "sts-session" + assert example.metadata["title"] == "What time is it" + assert example.metadata["model"] == "moonshotai/Kimi-K2-Instruct" + assert example.metadata["first_message_timestamp"] == "2026-07-01T15:00:00Z" + assert example.metadata["turn_count"] == 2 + assert example.prompt == "what time is it?" + assert example.messages == [ + {"role": "system", "content": "You are helpful."}, + {"role": "user", "content": "what time is it?"}, + { + "role": "assistant", + "content": "", + "reasoning_content": "I should check the clock.", + "tool_calls": [ + {"id": "t1", "type": "function", "function": {"name": "get_time", "arguments": {"tz": "UTC"}}}, + { + "id": "t2", + "type": "function", + "function": {"name": "apply_patch", "arguments": {"patch": "*** Begin Patch"}}, + }, + ], + }, + {"role": "tool", "tool_call_id": "t1", "name": "get_time", "content": "2026-07-01T15:00:00Z"}, + {"role": "tool", "tool_call_id": "t2", "name": "apply_patch", "content": "Done!"}, + {"role": "assistant", "content": "it is 15:00 UTC"}, + {"role": "user", "content": ""}, + {"role": "assistant", "content": "anything else?"}, + ] + assert [tool["function"]["name"] for tool in example.tools] == ["apply_patch", "get_time"] + assert validate_tool_calls(example.to_dict()).ok + + def test_convert_droid_trace_reads_settings_sidecar(tmp_path: Path): trace_file = tmp_path / "droid-settings.jsonl" events = [