langchain-curt 0.1.0__tar.gz

langchain_curt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Jordan Newell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_curt-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: langchain-curt
+Version: 0.1.0
+Summary: LangChain chat loader for .curt conversation files (.curt v1 — open single-file AI conversation format)
+Project-URL: Homepage, https://github.com/JordanNewell/langchain-curt
+Project-URL: Repository, https://github.com/JordanNewell/langchain-curt
+Project-URL: Documentation, https://github.com/JordanNewell/dot_curt
+Author: Jordan Newell
+License: MIT License
+        
+        Copyright (c) 2025-2026 Jordan Newell
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: langchain-core<2.0,>=0.3
+Description-Content-Type: text/markdown
+
+# langchain-curt
+
+[LangChain](https://github.com/langchain-ai/langchain) chat loader for
+[`.curt`](https://github.com/JordanNewell/dot_curt) — the open (MIT),
+single-file AI conversation format. One timestamped, attributed conversation
+per file; unknown fields are data and survive round-trips.
+
+```python
+from langchain_curt import CurtChatLoader
+
+loader = CurtChatLoader("./conversations/*.curt")
+sessions = loader.lazy_load()   # one ChatSession per .curt file
+```
+
+- **Role mapping:** `user` → `HumanMessage`, `assistant` → `AIMessage`,
+  `system` → `SystemMessage`. `tool` messages are skipped and counted
+  (`loader.stats["tool_messages_skipped"]`) — `ToolMessage` requires a
+  `tool_call_id` that `.curt` v1 does not carry.
+- **Metadata:** per-message timestamps (epoch ms → ISO 8601 UTC), model, and
+  all unknown/extension fields under `additional_kwargs["curt"]`;
+  conversation-level metadata in `loader.conversation_metadata`.
+- **Validation:** spec-compliant whole-file rejection (bad magic, wrong
+  version, missing fields → rejected, never half-loaded). `on_error="skip"`
+  imports valid files and reports invalid ones in `loader.errors`.
+- **Dependencies:** `langchain-core` only. The `.curt` parser is stdlib-only.
+
+Converters into `.curt` exist for Claude Code transcripts
+([curt-convert](https://github.com/JordanNewell/curt-convert)), Open WebUI
+exports ([curt-openwebui](https://github.com/JordanNewell/curt-openwebui)),
+and the WildChat-1M research corpus
+([curt-wildchat](https://github.com/JordanNewell/curt-wildchat)).
+
+Spec: https://github.com/JordanNewell/dot_curt · npm reference impl:
+[`curt-format`](https://www.npmjs.com/package/curt-format)
+
+## Development
+
+```sh
+pip install -e . pytest
+pytest
+```
+
+MIT License.

langchain_curt-0.1.0/README.md

@@ -0,0 +1,43 @@
+# langchain-curt
+
+[LangChain](https://github.com/langchain-ai/langchain) chat loader for
+[`.curt`](https://github.com/JordanNewell/dot_curt) — the open (MIT),
+single-file AI conversation format. One timestamped, attributed conversation
+per file; unknown fields are data and survive round-trips.
+
+```python
+from langchain_curt import CurtChatLoader
+
+loader = CurtChatLoader("./conversations/*.curt")
+sessions = loader.lazy_load()   # one ChatSession per .curt file
+```
+
+- **Role mapping:** `user` → `HumanMessage`, `assistant` → `AIMessage`,
+  `system` → `SystemMessage`. `tool` messages are skipped and counted
+  (`loader.stats["tool_messages_skipped"]`) — `ToolMessage` requires a
+  `tool_call_id` that `.curt` v1 does not carry.
+- **Metadata:** per-message timestamps (epoch ms → ISO 8601 UTC), model, and
+  all unknown/extension fields under `additional_kwargs["curt"]`;
+  conversation-level metadata in `loader.conversation_metadata`.
+- **Validation:** spec-compliant whole-file rejection (bad magic, wrong
+  version, missing fields → rejected, never half-loaded). `on_error="skip"`
+  imports valid files and reports invalid ones in `loader.errors`.
+- **Dependencies:** `langchain-core` only. The `.curt` parser is stdlib-only.
+
+Converters into `.curt` exist for Claude Code transcripts
+([curt-convert](https://github.com/JordanNewell/curt-convert)), Open WebUI
+exports ([curt-openwebui](https://github.com/JordanNewell/curt-openwebui)),
+and the WildChat-1M research corpus
+([curt-wildchat](https://github.com/JordanNewell/curt-wildchat)).
+
+Spec: https://github.com/JordanNewell/dot_curt · npm reference impl:
+[`curt-format`](https://www.npmjs.com/package/curt-format)
+
+## Development
+
+```sh
+pip install -e . pytest
+pytest
+```
+
+MIT License.

langchain_curt-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-curt"
+version = "0.1.0"
+description = "LangChain chat loader for .curt conversation files (.curt v1 — open single-file AI conversation format)"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Jordan Newell" }]
+requires-python = ">=3.10"
+dependencies = ["langchain-core>=0.3,<2.0"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/JordanNewell/langchain-curt"
+Repository = "https://github.com/JordanNewell/langchain-curt"
+Documentation = "https://github.com/JordanNewell/dot_curt"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_curt"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"

langchain_curt-0.1.0/src/langchain_curt/__init__.py

@@ -0,0 +1,19 @@
+"""langchain-curt: LangChain chat loader for `.curt` conversation files."""
+
+from langchain_curt.curt_chat import (
+    CurtChatLoader,
+    curt_ms_to_iso8601,
+    is_curt_conversation,
+    is_curt_message,
+    parse_curt,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CurtChatLoader",
+    "curt_ms_to_iso8601",
+    "is_curt_conversation",
+    "is_curt_message",
+    "parse_curt",
+]

langchain_curt-0.1.0/src/langchain_curt/curt_chat.py

@@ -0,0 +1,293 @@
+"""LangChain chat loader for `.curt` v1 conversation files.
+
+`.curt` is an open (MIT), single-file conversation format: one timestamped,
+attributed conversation per file with unknown fields preserved on round-trip.
+See https://github.com/JordanNewell/dot_curt (SPEC.md) — this module is a
+reader, not a reimplementation; the reference implementation and SPEC there
+are authoritative.
+
+Dependencies: langchain-core only (BaseChatLoader / ChatSession / messages).
+The parser below is stdlib-only and importable without langchain installed
+(the langchain imports are guarded).
+
+Spec: `.curt` v1 — https://github.com/JordanNewell/dot_curt (SPEC.md,
+"Validation rules (version 1)"). Whole-file rejection on any validation
+failure; unknown fields are data and must never cause a rejection.
+"""
+
+from __future__ import annotations
+
+import glob as _glob
+import json
+import math
+import os
+from collections.abc import Iterator
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+try:  # pragma: no cover - exercised only when langchain-core is installed
+    from langchain_core.chat_loaders import BaseChatLoader
+    from langchain_core.chat_sessions import ChatSession
+    from langchain_core.messages import (
+        AIMessage,
+        BaseMessage,
+        HumanMessage,
+        SystemMessage,
+    )
+
+    _LANGCHAIN_AVAILABLE = True
+except ImportError:  # pragma: no cover - parser-only standalone use
+    _LANGCHAIN_AVAILABLE = False
+
+# ---------------------------------------------------------------------------
+# .curt v1 parser — stdlib only, no langchain imports.
+# Mirrors the reference implementation (dot_curt src/index.ts: parseCurt,
+# isCurtConversation, isCurtMessage).
+# ---------------------------------------------------------------------------
+
+CURT_MAGIC = "curtis-conversation"
+CURT_VERSION = 1
+
+_CORE_MESSAGE_FIELDS = frozenset({"id", "role", "content", "timestamp", "model"})
+_CORE_CONVERSATION_FIELDS = frozenset(
+    {"id", "title", "createdAt", "updatedAt", "messages"}
+)
+
+
+def _is_str(value: Any) -> bool:
+    return isinstance(value, str)
+
+
+def _is_number(value: Any) -> bool:
+    # JSON numbers only: ``True`` is an ``int`` in Python but not a JSON number.
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def curt_ms_to_iso8601(ms: Any) -> str | None:
+    """Convert epoch milliseconds to an ISO 8601 UTC string.
+
+    Returns None for non-finite values (the spec's bulk convention treats
+    those as "no meaningful timestamp"); the raw number is kept in
+    ``additional_kwargs`` instead.
+    """
+    if not _is_number(ms) or not math.isfinite(ms):
+        return None
+    return (
+        datetime.fromtimestamp(ms / 1000, tz=timezone.utc)
+        .isoformat()
+        .replace("+00:00", "Z")
+    )
+
+
+def is_curt_message(value: Any) -> bool:
+    """Spec-valid message predicate (SPEC.md, "Each message in `messages`")."""
+    if not isinstance(value, dict):
+        return False
+    return (
+        _is_str(value.get("id"))
+        and value.get("role") in ("user", "assistant", "system", "tool")
+        and _is_str(value.get("content"))
+        and _is_number(value.get("timestamp"))
+    )
+
+
+def is_curt_conversation(value: Any) -> bool:
+    """Spec-valid conversation predicate (SPEC.md, "Validation rules")."""
+    if not isinstance(value, dict):
+        return False
+    messages = value.get("messages")
+    return (
+        _is_str(value.get("id"))
+        and _is_str(value.get("title"))
+        and _is_number(value.get("createdAt"))
+        and _is_number(value.get("updatedAt"))
+        and isinstance(messages, list)
+        and all(is_curt_message(m) for m in messages)
+    )
+
+
+def parse_curt(raw: str) -> dict | None:
+    """Parse a `.curt` file body. Returns the conversation dict or None.
+
+    Whole-file rejection: any validation failure returns None, never a
+    best-effort parse. Unknown fields on the top level, the conversation,
+    and messages are preserved verbatim (SPEC.md, "Unknown fields"). A
+    single leading UTF-8 BOM is ignored. ``version`` must be exactly the
+    number 1 — the string ``"1"`` and ``true`` are rejections.
+    """
+    raw = raw.removeprefix("")
+    try:
+        data = json.loads(raw)
+    except (ValueError, TypeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    # ``type() is int`` so that ``True`` (== 1 in Python) is rejected.
+    if data.get("curt") != CURT_MAGIC or type(data.get("version")) is not int:
+        return None
+    if data["version"] != CURT_VERSION:
+        return None
+    conversation = data.get("conversation")
+    return conversation if is_curt_conversation(conversation) else None
+
+
+def _extra_fields(obj: dict, core: frozenset) -> dict:
+    """Unknown fields are data: preserved verbatim, never interpreted."""
+    return {k: v for k, v in obj.items() if k not in core}
+
+
+# ---------------------------------------------------------------------------
+# Loader — requires langchain-core.
+# ---------------------------------------------------------------------------
+
+if _LANGCHAIN_AVAILABLE:
+
+    class CurtChatLoader(BaseChatLoader):
+        """Load `.curt` v1 conversation files into LangChain chat sessions.
+
+        Spec: https://github.com/JordanNewell/dot_curt (SPEC.md, v1).
+        Each file yields one :class:`~langchain_core.chat_sessions.ChatSession`.
+
+        Args:
+            paths: A single path or glob pattern (``str`` or ``Path``), or a
+                list of them. Glob patterns are resolved and sorted for
+                deterministic ordering.
+            on_error: ``"raise"`` (default) rejects the whole batch with a
+                ``ValueError`` on the first invalid file, matching the spec's
+                whole-file-rejection rule. ``"skip"`` matches the spec's bulk
+                convention instead: invalid files are reported (in
+                :attr:`errors`, never silently dropped) and valid ones load.
+
+        Role mapping: ``user`` -> HumanMessage, ``assistant`` -> AIMessage,
+        ``system`` -> SystemMessage. ``tool`` messages are **skipped and
+        counted** (see :attr:`stats`): ToolMessage requires a
+        ``tool_call_id``, which `.curt` v1 does not carry (message ``id`` is
+        a conversation-local identifier, not tool-call linkage), so a lossy
+        conversion would misrepresent agent traces.
+
+        Metadata: per-message timestamp (converted from epoch ms to ISO 8601
+        UTC), ``model``, and any unknown/extension fields are preserved under
+        ``additional_kwargs["curt"]``. Conversation-level metadata (``id``,
+        ``title``, ``createdAt``/``updatedAt`` as ISO 8601, ``generator``,
+        unknown fields, per-file counts) is collected in
+        :attr:`conversation_metadata` because ChatSession carries no
+        metadata slot of its own.
+
+        Attributes:
+            stats: Running counters (``files_loaded``, ``files_failed``,
+                ``messages_loaded``, ``tool_messages_skipped``).
+            errors: ``(path, reason)`` tuples for files rejected under
+                ``on_error="skip"``.
+            conversation_metadata: One metadata dict per loaded file, in
+                load order.
+        """
+
+        def __init__(
+            self,
+            paths: str | Path | list[str | Path],
+            *,
+            on_error: str = "raise",
+        ) -> None:
+            if on_error not in ("raise", "skip"):
+                msg = f"on_error must be 'raise' or 'skip', got {on_error!r}"
+                raise ValueError(msg)
+            self._patterns: list[str | Path] = (
+                list(paths) if isinstance(paths, (list, tuple)) else [paths]
+            )
+            self.on_error = on_error
+            self.stats = {
+                "files_loaded": 0,
+                "files_failed": 0,
+                "messages_loaded": 0,
+                "tool_messages_skipped": 0,
+            }
+            self.errors: list[Any] = []
+            self.conversation_metadata: list[dict] = []
+
+        def _resolve_files(self) -> list[Path]:
+            files: list[Path] = []
+            for pattern in self._patterns:
+                matches = sorted(_glob.glob(os.fspath(pattern)))
+                if not matches and not any(c in os.fspath(pattern) for c in "*?["):
+                    # A literal path that does not exist is an error, even
+                    # under on_error="skip": unlike a corrupt file, the user
+                    # almost certainly mistyped it.
+                    raise FileNotFoundError(os.fspath(pattern))
+                files.extend(Path(m) for m in matches)
+            if not files:
+                msg = f"No .curt files matched: {self._patterns!r}"
+                raise ValueError(msg)
+            return files
+
+        def _load_file(self, path: Path) -> ChatSession:
+            conversation = parse_curt(path.read_text(encoding="utf-8"))
+            if conversation is None:
+                msg = (
+                    f"{path}: not a valid .curt v1 file "
+                    "(bad JSON, wrong magic/version, or failed validation; "
+                    "see https://github.com/JordanNewell/dot_curt)"
+                )
+                raise ValueError(msg)
+
+            messages: list[BaseMessage] = []
+            tool_skipped = 0
+            for m in conversation["messages"]:
+                role = m["role"]
+                if role == "tool":
+                    tool_skipped += 1
+                    continue
+                curt_kwargs: dict = {
+                    "message_id": m["id"],
+                    "conversation_id": conversation["id"],
+                    "conversation_title": conversation["title"],
+                    "timestamp": curt_ms_to_iso8601(m["timestamp"]),
+                    "unknown_fields": _extra_fields(m, _CORE_MESSAGE_FIELDS),
+                }
+                if curt_kwargs["timestamp"] is None:
+                    curt_kwargs["timestamp_raw_ms"] = m["timestamp"]
+                if "model" in m:
+                    curt_kwargs["model"] = m["model"]
+                cls = {
+                    "user": HumanMessage,
+                    "assistant": AIMessage,
+                    "system": SystemMessage,
+                }[role]
+                messages.append(
+                    cls(content=m["content"], additional_kwargs={"curt": curt_kwargs})
+                )
+
+            created = curt_ms_to_iso8601(conversation["createdAt"])
+            updated = curt_ms_to_iso8601(conversation["updatedAt"])
+            meta = {
+                "source": str(path),
+                "id": conversation["id"],
+                "title": conversation["title"],
+                "created_at": created,
+                "updated_at": updated,
+                "generator": None,  # readers must ignore `generator` (spec)
+                "unknown_fields": _extra_fields(
+                    conversation, _CORE_CONVERSATION_FIELDS
+                ),
+                "tool_messages_skipped": tool_skipped,
+            }
+            for key in ("created_at", "updated_at"):
+                if meta[key] is None:
+                    meta[key + "_raw_ms"] = conversation[
+                        "createdAt" if key == "created_at" else "updatedAt"
+                    ]
+            self.conversation_metadata.append(meta)
+            self.stats["files_loaded"] += 1
+            self.stats["messages_loaded"] += len(messages)
+            self.stats["tool_messages_skipped"] += tool_skipped
+            return ChatSession(messages=messages)
+
+        def lazy_load(self) -> Iterator[ChatSession]:
+            for path in self._resolve_files():
+                try:
+                    yield self._load_file(path)
+                except (ValueError, OSError) as e:
+                    if self.on_error == "raise":
+                        raise
+                    self.stats["files_failed"] += 1
+                    self.errors.append((str(path), str(e)))

langchain_curt-0.1.0/tests/test_curt_chat.py

@@ -0,0 +1,288 @@
+"""Tests for CurtChatLoader.
+
+All fixtures are synthetic. Never load real conversation content in tests.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from langchain_curt.curt_chat import (
+    CurtChatLoader,
+    curt_ms_to_iso8601,
+    is_curt_conversation,
+    is_curt_message,
+    parse_curt,
+)
+
+MAGIC = "curtis-conversation"
+
+
+def curt_body(
+    conv_id="conv_001",
+    title="Test Conversation",
+    messages=None,
+    **top_extra,
+):
+    """Build a minimal valid .curt v1 body. All content is synthetic."""
+    if messages is None:
+        messages = [
+            {
+                "id": "m1",
+                "role": "user",
+                "content": "Hello",
+                "timestamp": 1700000000000,
+            },
+            {
+                "id": "m2",
+                "role": "assistant",
+                "content": "Hi there",
+                "timestamp": 1700000001000,
+                "model": "test-model",
+            },
+        ]
+    body = {
+        "curt": MAGIC,
+        "version": 1,
+        "generator": "synthetic-fixture@0.0.1",
+        "conversation": {
+            "id": conv_id,
+            "title": title,
+            "createdAt": 1700000000000,
+            "updatedAt": 1700000001000,
+            "messages": messages,
+        },
+    }
+    body.update(top_extra)
+    return body
+
+
+def write_curt(path, body):
+    path.write_text(json.dumps(body, indent="\t"), encoding="utf-8")
+    return path
+
+
+def load_one(loader):
+    sessions = list(loader.lazy_load())
+    return sessions
+
+
+class TestHappyPath:
+    def test_single_file(self, tmp_path):
+        f = write_curt(tmp_path / "a.curt", curt_body())
+        loader = CurtChatLoader(f)
+        sessions = load_one(loader)
+        assert len(sessions) == 1
+        msgs = sessions[0]["messages"]
+        assert [type(m).__name__ for m in msgs] == ["HumanMessage", "AIMessage"]
+        assert msgs[0].content == "Hello"
+        assert msgs[1].content == "Hi there"
+        assert msgs[1].additional_kwargs["curt"]["model"] == "test-model"
+        # Timestamps: epoch ms -> ISO 8601 UTC.
+        assert msgs[0].additional_kwargs["curt"]["timestamp"] == (
+            "2023-11-14T22:13:20Z"
+        )
+        assert loader.stats["files_loaded"] == 1
+        assert loader.stats["messages_loaded"] == 2
+        assert loader.errors == []
+
+    def test_conversation_metadata_collected(self, tmp_path):
+        f = write_curt(tmp_path / "a.curt", curt_body())
+        loader = CurtChatLoader(f)
+        load_one(loader)
+        (meta,) = loader.conversation_metadata
+        assert meta["id"] == "conv_001"
+        assert meta["title"] == "Test Conversation"
+        assert meta["created_at"] == "2023-11-14T22:13:20Z"
+        assert meta["source"].endswith("a.curt")
+
+    def test_system_role(self, tmp_path):
+        msgs = [
+            {"id": "m0", "role": "system", "content": "You are terse.", "timestamp": 0},
+            {"id": "m1", "role": "user", "content": "Hi", "timestamp": 1},
+        ]
+        f = write_curt(tmp_path / "a.curt", curt_body(messages=msgs))
+        (session,) = load_one(CurtChatLoader(f))
+        assert type(session["messages"][0]).__name__ == "SystemMessage"
+
+    def test_timestamp_zero_and_fractional(self):
+        assert curt_ms_to_iso8601(0) == "1970-01-01T00:00:00Z"
+        # Spec: validators accept any JSON number; never reject fractional.
+        assert curt_ms_to_iso8601(1700000000123.5) == "2023-11-14T22:13:20.123500Z"
+
+
+class TestMultiFile:
+    def test_glob(self, tmp_path):
+        for i in (2, 1):
+            write_curt(tmp_path / f"chat{i}.curt", curt_body(conv_id=f"conv_{i:03d}"))
+        loader = CurtChatLoader(str(tmp_path / "*.curt"))
+        sessions = load_one(loader)
+        assert len(sessions) == 2
+        # Sorted for deterministic ordering.
+        assert loader.conversation_metadata[0]["id"] == "conv_001"
+
+    def test_path_list(self, tmp_path):
+        fa = write_curt(tmp_path / "a.curt", curt_body(conv_id="a"))
+        fb = write_curt(tmp_path / "b.curt", curt_body(conv_id="b"))
+        sessions = load_one(CurtChatLoader([fa, fb]))
+        assert [
+            m["messages"][0].additional_kwargs["curt"]["conversation_id"]
+            for m in sessions
+        ] == ["a", "b"]
+
+    def test_no_matches_raises(self, tmp_path):
+        with pytest.raises(ValueError, match="No .curt files matched"):
+            load_one(CurtChatLoader(str(tmp_path / "*.curt")))
+
+    def test_missing_literal_path_raises(self, tmp_path):
+        with pytest.raises(FileNotFoundError):
+            load_one(CurtChatLoader(tmp_path / "nope.curt"))
+
+
+class TestRejections:
+    """Whole-file rejection per spec — a corrupted file is never half-loaded."""
+
+    def test_bad_magic_string(self, tmp_path):
+        write_curt(tmp_path / "a.curt", curt_body(curt="wrong-magic"))
+        with pytest.raises(ValueError, match="not a valid .curt v1 file"):
+            load_one(CurtChatLoader(tmp_path / "a.curt"))
+
+    def test_version_as_string(self, tmp_path):
+        write_curt(tmp_path / "a.curt", curt_body(version="1"))
+        with pytest.raises(ValueError, match="not a valid .curt v1 file"):
+            load_one(CurtChatLoader(tmp_path / "a.curt"))
+
+    def test_version_true_rejected(self, tmp_path):
+        # Python gotcha the parser must guard: True == 1.
+        write_curt(tmp_path / "a.curt", curt_body(version=True))
+        assert parse_curt((tmp_path / "a.curt").read_text(encoding="utf-8")) is None
+
+    def test_unknown_role_rejects_whole_file(self, tmp_path):
+        # Spec: role must be user/assistant/system/tool; anything else fails
+        # message validation, and failure is whole-file — the valid messages
+        # in the same file must NOT load.
+        msgs = [
+            {"id": "m1", "role": "user", "content": "ok", "timestamp": 1},
+            {"id": "m2", "role": "moderator", "content": "nope", "timestamp": 2},
+        ]
+        write_curt(tmp_path / "a.curt", curt_body(messages=msgs))
+        with pytest.raises(ValueError, match="not a valid .curt v1 file"):
+            load_one(CurtChatLoader(tmp_path / "a.curt"))
+
+    def test_missing_required_message_field(self, tmp_path):
+        msgs = [{"id": "m1", "role": "user", "content": "no timestamp"}]
+        write_curt(tmp_path / "a.curt", curt_body(messages=msgs))
+        with pytest.raises(ValueError):
+            load_one(CurtChatLoader(tmp_path / "a.curt"))
+
+    def test_malformed_json(self, tmp_path):
+        (tmp_path / "a.curt").write_text("{not json", encoding="utf-8")
+        with pytest.raises(ValueError, match="not a valid .curt v1 file"):
+            load_one(CurtChatLoader(tmp_path / "a.curt"))
+
+    def test_non_object_body(self, tmp_path):
+        (tmp_path / "a.curt").write_text('["a"]', encoding="utf-8")
+        assert parse_curt('["a"]') is None
+
+    def test_skip_mode_reports(self, tmp_path):
+        write_curt(tmp_path / "good.curt", curt_body())
+        write_curt(tmp_path / "bad.curt", curt_body(curt="nope"))
+        loader = CurtChatLoader(str(tmp_path / "*.curt"), on_error="skip")
+        sessions = load_one(loader)
+        assert len(sessions) == 1
+        assert loader.stats["files_loaded"] == 1
+        assert loader.stats["files_failed"] == 1
+        assert len(loader.errors) == 1
+        assert "bad.curt" in loader.errors[0][0]
+
+    def test_bad_on_error_arg(self):
+        with pytest.raises(ValueError, match="on_error"):
+            CurtChatLoader("x", on_error="explode")
+
+
+class TestToolRole:
+    def test_tool_messages_skipped_and_counted(self, tmp_path):
+        msgs = [
+            {"id": "m1", "role": "user", "content": "q", "timestamp": 1},
+            {
+                "id": "m2",
+                "role": "tool",
+                "content": '{"result": 42}',
+                "timestamp": 2,
+            },
+            {"id": "m3", "role": "assistant", "content": "a", "timestamp": 3},
+        ]
+        write_curt(tmp_path / "a.curt", curt_body(messages=msgs))
+        loader = CurtChatLoader(tmp_path / "a.curt")
+        (session,) = load_one(loader)
+        # Documented loss: tool -> skipped (ToolMessage needs tool_call_id).
+        assert [type(m).__name__ for m in session["messages"]] == [
+            "HumanMessage",
+            "AIMessage",
+        ]
+        assert loader.stats["tool_messages_skipped"] == 1
+        assert loader.conversation_metadata[0]["tool_messages_skipped"] == 1
+
+
+class TestSpecCompliance:
+    def test_bom_tolerated(self, tmp_path):
+        f = tmp_path / "a.curt"
+        f.write_text("" + json.dumps(curt_body()), encoding="utf-8")
+        sessions = load_one(CurtChatLoader(f))
+        assert len(sessions) == 1
+
+    def test_unknown_fields_preserved(self, tmp_path):
+        msgs = [
+            {
+                "id": "m1",
+                "role": "user",
+                "content": "hi",
+                "timestamp": 1,
+                "tokens": 5,
+                "images-inline": {"v": 1},
+            }
+        ]
+        body = curt_body(messages=msgs, extensions=["images-inline"])
+        body["conversation"]["folder_hint"] = "keep-me"
+        f = write_curt(tmp_path / "a.curt", body)
+        loader = CurtChatLoader(f)
+        (session,) = load_one(loader)
+        kwargs = session["messages"][0].additional_kwargs["curt"]
+        # Unknown fields are data: preserved verbatim, never a rejection.
+        assert kwargs["unknown_fields"] == {
+            "tokens": 5,
+            "images-inline": {"v": 1},
+        }
+        meta = loader.conversation_metadata[0]
+        assert meta["unknown_fields"] == {"folder_hint": "keep-me"}
+        # `generator` must be ignored by readers (spec), never validated on.
+        assert meta["generator"] is None
+
+    def test_empty_title_allowed(self, tmp_path):
+        f = write_curt(tmp_path / "a.curt", curt_body(title=""))
+        (session,) = load_one(CurtChatLoader(f))
+        assert (
+            session["messages"][0].additional_kwargs["curt"]["conversation_title"] == ""
+        )
+
+    def test_empty_messages_accepted(self, tmp_path):
+        # Spec: readers may accept empty message arrays.
+        f = write_curt(tmp_path / "a.curt", curt_body(messages=[]))
+        (session,) = load_one(CurtChatLoader(f))
+        assert session["messages"] == []
+
+    def test_predicates(self):
+        assert is_curt_message(
+            {"id": "m", "role": "user", "content": "c", "timestamp": 0}
+        )
+        assert not is_curt_message(
+            {"id": "m", "role": "user", "content": "c", "timestamp": True}
+        )
+        assert not is_curt_conversation(
+            {"id": "c", "title": "t", "createdAt": 0, "updatedAt": 0}
+        )
+        assert is_curt_conversation(
+            {"id": "c", "title": "t", "createdAt": 0, "updatedAt": 0, "messages": []}
+        )