rlmness-cli 0.2.0__py3-none-any.whl

rlmagent/harness/contracts/tooling.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+from pydantic import Field, model_validator
+
+from rlmagent.harness.contracts.transcript import (
+    ImageSegment,
+    StrictModel,
+    TextSegment,
+)
+from rlmagent.harness.contracts.values import JValue
+
+Parallelism = Literal["parallel", "sequential"]
+InputShaper = Callable[[object], Mapping[str, JValue]]
+ProgressNotifier = Callable[["ToolOutcome"], None]
+
+
+class CancelToken(Protocol):
+    def is_cancelled(self) -> bool: ...
+
+
+class InvocationPrinter(Protocol):
+    def __call__(
+        self,
+        arguments: Mapping[str, JValue],
+    ) -> str | None: ...
+
+
+class OutcomePresenter(Protocol):
+    def __call__(
+        self,
+        result: ToolOutcome,
+        *,
+        expanded: bool,
+    ) -> str | None: ...
+
+
+class RunHandler(Protocol):
+    def __call__(
+        self,
+        tool_call_id: str,
+        arguments: Mapping[str, JValue],
+        signal: CancelToken | None = None,
+        on_update: ProgressNotifier | None = None,
+    ) -> Awaitable[ToolOutcome]: ...
+
+
+class ToolOutcome(StrictModel):
+    content: list[TextSegment | ImageSegment] = Field(default_factory=list)
+    details: JValue = None
+    terminate: bool | None = None
+    added_tool_names: list[str] | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def coerce_content(cls, value):
+        if not isinstance(value, dict):
+            return value
+
+        data = dict(value)
+
+        if isinstance(data.get("content"), str):
+            text = data["content"]
+            data["content"] = [TextSegment(text=text)] if text else []
+
+        return data
+
+    @property
+    def text(self) -> str:
+        return "".join(
+            block.text
+            for block in self.content
+            if isinstance(block, TextSegment)
+        )
+
+
+@dataclass(slots=True, frozen=True)
+class ToolSpec:
+    name: str
+    label: str
+    description: str
+    parameters: Mapping[str, JValue]
+    run: RunHandler
+
+    parallelism: Parallelism = "parallel"
+
+    prompt_snippet: str | None = None
+    prompt_guidelines: tuple[str, ...] = ()
+
+    input_shaper: InputShaper | None = None
+
+    format_call: InvocationPrinter | None = None
+    format_result: OutcomePresenter | None = None
+
+    @property
+    def input_schema(self) -> Mapping[str, JValue]:
+        return self.parameters
+
+    async def execute(
+        self,
+        tool_call_id: str,
+        arguments: Mapping[str, JValue],
+        signal: CancelToken | None = None,
+        on_update: ProgressNotifier | None = None,
+    ) -> ToolOutcome:
+        return await self.run(
+            tool_call_id,
+            arguments,
+            signal,
+            on_update,
+        )
+
+
+__all__ = [
+    "CancelToken",
+    "InputShaper",
+    "InvocationPrinter",
+    "OutcomePresenter",
+    "Parallelism",
+    "ProgressNotifier",
+    "RunHandler",
+    "ToolOutcome",
+    "ToolSpec",
+]

rlmagent/harness/contracts/transcript/__init__.py

@@ -0,0 +1,68 @@
+"""Provider-neutral content and transcript message models."""
+
+from __future__ import annotations
+
+from rlmagent.harness.contracts.transcript._base import StrictModel, now_ms
+from rlmagent.harness.contracts.transcript.diagnostics import (
+    CostBreakdown,
+    FaultInfo,
+    HaltReason,
+    TurnDiagnostic,
+    UsageStats,
+)
+from rlmagent.harness.contracts.transcript.entries import (
+    ExtensionEntry,
+    ForkSummaryEntry,
+    HumanEntry,
+    ModelEntry,
+    PruneSummaryEntry,
+    ShellResultEntry,
+    ToolOutcomeEntry,
+    TranscriptEntry,
+    entry_to_human,
+    surface_text,
+)
+from rlmagent.harness.contracts.transcript.segments import (
+    CallBlock,
+    ImageSegment,
+    InputContent,
+    ReplyContent,
+    ResultContent,
+    TextSegment,
+    ThoughtSegment,
+    build_model_blocks,
+    gather_text,
+)
+
+__all__ = [
+    # base
+    "StrictModel",
+    "now_ms",
+    # segments
+    "CallBlock",
+    "ImageSegment",
+    "InputContent",
+    "ReplyContent",
+    "ResultContent",
+    "TextSegment",
+    "ThoughtSegment",
+    "build_model_blocks",
+    "gather_text",
+    # diagnostics
+    "CostBreakdown",
+    "FaultInfo",
+    "HaltReason",
+    "TurnDiagnostic",
+    "UsageStats",
+    # entries
+    "ExtensionEntry",
+    "ForkSummaryEntry",
+    "HumanEntry",
+    "ModelEntry",
+    "PruneSummaryEntry",
+    "ShellResultEntry",
+    "ToolOutcomeEntry",
+    "TranscriptEntry",
+    "entry_to_human",
+    "surface_text",
+]

rlmagent/harness/contracts/transcript/_base.py

@@ -0,0 +1,29 @@
+"""Base model config and timestamp helpers for transcript types."""
+
+from __future__ import annotations
+
+from time import time
+
+from pydantic import BaseModel, ConfigDict
+
+
+def _camelize(name: str) -> str:
+    parts = name.split("_")
+    return parts[0] + "".join(part.title() for part in parts[1:])
+
+
+def now_ms() -> int:
+    """Return the current Unix timestamp in milliseconds."""
+    return int(time() * 1000)
+
+
+class StrictModel(BaseModel):
+    """Strict model with Python field names and wire-compatible JSON aliases."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        validate_by_name=True,
+        serialize_by_alias=True,
+        alias_generator=_camelize,
+    )

rlmagent/harness/contracts/transcript/diagnostics.py

@@ -0,0 +1,52 @@
+"""Usage, cost, and diagnostic metadata for assistant responses."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from rlmagent.harness.contracts.transcript._base import StrictModel, now_ms
+from rlmagent.harness.contracts.values import JValue
+
+
+class CostBreakdown(StrictModel):
+
+    total: float = 0.0
+    input: float = 0.0
+    output: float = 0.0
+    cache_read: float = 0.0
+    cache_write: float = 0.0
+
+
+class UsageStats(StrictModel):
+
+    total_tokens: int = 0
+    input: int = 0
+    output: int = 0
+    cache_read: int = 0
+    cache_write: int = 0
+    cache_write_1h: int | None = None
+    reasoning: int | None = None
+    cost: CostBreakdown = CostBreakdown()
+
+
+class FaultInfo(StrictModel):
+    
+
+    message: str
+    code: str | int | None = None
+    name: str | None = None
+    stack: str | None = None
+
+
+class TurnDiagnostic(StrictModel):
+
+
+    type: str
+    error: FaultInfo | None = None
+    details: dict[str, JValue] | None = None
+    timestamp: int = Field(default_factory=now_ms)
+
+
+HaltReason = Literal["stop", "length", "toolUse", "error", "aborted"]

rlmagent/harness/contracts/transcript/entries.py

@@ -0,0 +1,180 @@
+"""Transcript entry types and the discriminated TranscriptEntry union."""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import Field, model_validator
+
+from rlmagent.harness.contracts.transcript._base import StrictModel, now_ms
+from rlmagent.harness.contracts.transcript.diagnostics import HaltReason, TurnDiagnostic, UsageStats
+from rlmagent.harness.contracts.transcript.segments import (
+    CallBlock,
+    InputContent,
+    ReplyContent,
+    ResultContent,
+    TextSegment,
+    ThoughtSegment,
+    gather_text,
+)
+from rlmagent.harness.contracts.values import JValue
+
+
+class HumanEntry(StrictModel):
+    """User-authored transcript entry."""
+
+    role: Literal["user"] = "user"
+    content: InputContent
+    timestamp: int = Field(default_factory=now_ms)
+
+    @property
+    def text(self) -> str:
+        return gather_text(self.content)
+
+
+class ModelEntry(StrictModel):
+    """An assistant message with ordered content blocks."""
+
+    role: Literal["assistant"] = "assistant"
+    content: list[ReplyContent] = Field(default_factory=list)
+    model: str = "unknown"
+    provider: str = "unknown"
+    api: str = "unknown"
+    response_model: str | None = None
+    response_id: str | None = None
+    stop_reason: HaltReason = "stop"
+    usage: UsageStats = UsageStats()
+    error_message: str | None = None
+    diagnostics: list[TurnDiagnostic] | None = None
+    timestamp: int = Field(default_factory=now_ms)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_str_blocks(cls, value: object) -> object:
+        if not isinstance(value, dict):
+            return value
+        data = dict(value)
+        content = data.get("content")
+        if isinstance(content, str):
+            data["content"] = [TextSegment(text=content)] if content else []
+        usage = data.get("usage")
+        if usage is None:
+            data["usage"] = UsageStats()
+        return data
+
+    @property
+    def text(self) -> str:
+        return "".join(block.text for block in self.content if isinstance(block, TextSegment))
+
+    @property
+    def tool_calls(self) -> tuple[CallBlock, ...]:
+        return tuple(block for block in self.content if isinstance(block, CallBlock))
+
+    @property
+    def thinking_text(self) -> str:
+        return "".join(
+            block.thinking for block in self.content if isinstance(block, ThoughtSegment)
+        )
+
+
+class ToolOutcomeEntry(StrictModel):
+    """Result of a single tool invocation."""
+
+    role: Literal["toolResult"] = "toolResult"
+    tool_call_id: str
+    tool_name: str
+    content: list[ResultContent] = Field(default_factory=list)
+    is_error: bool = False
+    details: JValue = None
+    added_tool_names: list[str] | None = None
+    timestamp: int = Field(default_factory=now_ms)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_str_blocks(cls, value: object) -> object:
+        if not isinstance(value, dict):
+            return value
+        data = dict(value)
+        content = data.get("content")
+        if isinstance(content, str):
+            data["content"] = [TextSegment(text=content)] if content else []
+        return data
+
+    @property
+    def text(self) -> str:
+        return gather_text(self.content)
+
+
+class ShellResultEntry(StrictModel):
+    """Captured output from a shell command execution."""
+
+    role: Literal["bashExecution"] = "bashExecution"
+    command: str
+    output: str
+    exit_code: int | None = None
+    truncated: bool = False
+    cancelled: bool = False
+    full_output_path: str | None = None
+    exclude_from_context: bool = False
+    timestamp: int = Field(default_factory=now_ms)
+
+
+class ExtensionEntry(StrictModel):
+    """Application-defined custom transcript entry."""
+
+    role: Literal["custom"] = "custom"
+    custom_type: str
+    content: InputContent
+    details: JValue = None
+    display: bool = True
+    timestamp: int = Field(default_factory=now_ms)
+
+    @property
+    def text(self) -> str:
+        return gather_text(self.content)
+
+
+class PruneSummaryEntry(StrictModel):
+    """Summary produced when compacting conversation history."""
+
+    role: Literal["compactionSummary"] = "compactionSummary"
+    summary: str
+    tokens_before: int
+    timestamp: int = Field(default_factory=now_ms)
+
+
+class ForkSummaryEntry(StrictModel):
+    """Summary produced when branching a conversation."""
+
+    role: Literal["branchSummary"] = "branchSummary"
+    summary: str
+    from_id: str
+    timestamp: int = Field(default_factory=now_ms)
+
+
+type TranscriptEntry = Annotated[
+    HumanEntry
+    | ModelEntry
+    | ToolOutcomeEntry
+    | ShellResultEntry
+    | ExtensionEntry
+    | PruneSummaryEntry
+    | ForkSummaryEntry,
+    Field(discriminator="role"),
+]
+
+
+def surface_text(message: TranscriptEntry) -> str:
+    """Return the user-visible text of a transcript entry."""
+    if isinstance(message, (HumanEntry, ModelEntry, ToolOutcomeEntry, ExtensionEntry)):
+        return message.text
+    if isinstance(message, (ForkSummaryEntry, PruneSummaryEntry)):
+        return message.summary
+    if isinstance(message, ShellResultEntry):
+        return message.output
+    return ""
+
+
+def entry_to_human(message: TranscriptEntry) -> HumanEntry:
+    """Convert custom/session-only messages to provider-compatible user context."""
+    return HumanEntry(content=surface_text(message), timestamp=message.timestamp)

rlmagent/harness/contracts/transcript/segments.py

@@ -0,0 +1,64 @@
+"""Content segments and blocks that make up transcript entries."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import Field
+
+from rlmagent.harness.contracts.transcript._base import StrictModel
+from rlmagent.harness.contracts.values import JValue
+
+
+class TextSegment(StrictModel):
+
+    type: Literal["text"] = "text"
+    text: str
+    text_signature: str | None = None
+
+
+class ImageSegment(StrictModel):
+
+    type: Literal["image"] = "image"
+    mime_type: str
+    data: str
+
+
+class ThoughtSegment(StrictModel):
+
+
+    type: Literal["thinking"] = "thinking"
+    thinking: str
+    redacted: bool = False
+    thinking_signature: str | None = None
+
+
+class CallBlock(StrictModel):
+
+    type: Literal["toolCall"] = "toolCall"
+    name: str
+    id: str
+    arguments: dict[str, JValue] = Field(default_factory=dict)
+    thought_signature: str | None = None
+
+
+type InputContent = str | list[TextSegment | ImageSegment]
+type ReplyContent = TextSegment | ThoughtSegment | CallBlock
+type ResultContent = TextSegment | ImageSegment
+
+
+def gather_text(content: str | list[Any]) -> str:
+    """Return visible text from string or text/image content."""
+    if isinstance(content, str):
+        return content
+    return "".join(block.text for block in content if isinstance(block, TextSegment))
+
+
+def build_model_blocks(
+    text: str,
+    tool_calls: list[CallBlock] | tuple[CallBlock, ...] = (),
+) -> list[ReplyContent]:
+    """Build canonical ordered assistant blocks from parser accumulators."""
+    blocks: list[ReplyContent] = [TextSegment(text=text)] if text else []
+    blocks.extend(tool_calls)
+    return blocks

rlmagent/harness/contracts/values.py

@@ -0,0 +1,6 @@
+
+from __future__ import annotations
+
+type JPrimitive = str | int | float | bool | None
+type JValue = JPrimitive | list[JValue] | dict[str, JValue]
+type JObject = dict[str, JValue]