Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/python-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<session-id>.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
Expand Down
9 changes: 9 additions & 0 deletions examples/example_sts_session.jsonl
Original file line number Diff line number Diff line change
@@ -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}}
139 changes: 138 additions & 1 deletion src/teich/converter.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
{
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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,
}
Comment on lines +2920 to +2924

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve failed STS tool results

When an STS role: "tool" event carries isError: true, this newly constructed message discards the flag and emits only the output text. The other trace converters normalize failed results to is_error: true, so these STS rows make failures indistinguishable from successful calls and can corrupt SFT supervision; copy the flag onto the normalized tool message.

Useful? React with 👍 / 👎.

)
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]],
Expand Down Expand Up @@ -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":
Expand Down Expand Up @@ -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 [
Expand Down
102 changes: 101 additions & 1 deletion tests/test_converter.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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):
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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 = [
Expand Down
Loading