llm-tool-cli 0.2.0__py3-none-any.whl

llm_tool_cli/core/tests/test_settings.py

@@ -0,0 +1,64 @@
+from contextvars import Context
+
+import pytest
+
+from llm_tool_cli.core import settings
+from llm_tool_cli.core.errors import ContextValueAlreadySet, ContextValueNotSet, ToolLabelAlreadyInitialized
+from llm_tool_cli.core.settings import ConfigFilename, ToolLabel, initialize
+from llm_tool_cli.core.tests.fixtures import isolated_settings
+
+__all__ = ["isolated_settings"]
+
+pytestmark = pytest.mark.usefixtures("isolated_settings")
+
+
+class TestInitialize:
+    @pytest.mark.parametrize("label", ["TOOL", "", "  café 日本語  "])
+    def test_installs_exact_label(self, label: str) -> None:
+        initialize(label=ToolLabel(label))
+
+        assert settings.static_config.get().tool_label == label
+
+    def test_same_label_is_idempotent(self) -> None:
+        initialize(label=ToolLabel("TOOL"))
+        initialize(label=ToolLabel("TOOL"))
+
+        assert settings.static_config.get().tool_label == "TOOL"
+
+    def test_same_application_settings_are_idempotent(self) -> None:
+        initialize(label=ToolLabel("TOOL"), config_filename=ConfigFilename("tool.toml"))
+        initialize(label=ToolLabel("TOOL"), config_filename=ConfigFilename("tool.toml"))
+
+        assert settings.static_config.get().config_filename == "tool.toml"
+
+    @pytest.mark.parametrize("filename", [None, ConfigFilename("other.toml")])
+    def test_conflicting_filename_preserves_original(self, filename: ConfigFilename | None) -> None:
+        initialize(label=ToolLabel("TOOL"), config_filename=ConfigFilename("tool.toml"))
+
+        with pytest.raises(ContextValueAlreadySet) as caught:
+            initialize(label=ToolLabel("TOOL"), config_filename=filename)
+
+        assert caught.value.details == {"name": "static_config"}
+        assert settings.static_config.get().config_filename == "tool.toml"
+
+    def test_conflicting_label_preserves_original(self) -> None:
+        initialize(label=ToolLabel(""))
+
+        with pytest.raises(ToolLabelAlreadyInitialized) as caught:
+            initialize(label=ToolLabel("OTHER"))
+
+        assert caught.value.details == {"current": "", "requested": "OTHER"}
+        assert settings.static_config.get().tool_label == ""
+
+    def test_initialization_uses_current_execution_context(self) -> None:
+        initialize(label=ToolLabel("OUTER"))
+        execution = Context()
+
+        with pytest.raises(ContextValueNotSet) as caught:
+            execution.run(settings.static_config.get)
+
+        assert caught.value.details == {"name": "static_config"}
+        execution.run(initialize, label=ToolLabel("INNER"))
+
+        assert execution.run(settings.static_config.get).tool_label == "INNER"
+        assert settings.static_config.get().tool_label == "OUTER"

llm_tool_cli/output/__init__.py

@@ -0,0 +1,3 @@
+from llm_tool_cli.output.emitter import JournalCellFactory, OutputEmitter, StreamOutputEmitter, output
+
+__all__ = ["JournalCellFactory", "OutputEmitter", "StreamOutputEmitter", "output"]

llm_tool_cli/output/emitter.py

@@ -0,0 +1,108 @@
+import sys
+from types import EllipsisType
+from typing import Protocol, TextIO
+
+from llm_tool_cli.config.runtime import runtime_config
+from llm_tool_cli.core import settings
+from llm_tool_cli.core.context import ContextValue
+from llm_tool_cli.core.result import Ok, Result, unwrap_to_error
+from llm_tool_cli.output.journal import JournalProcessor, NoopJournalProcessor
+from llm_tool_cli.protocol import Protocol as OutputProtocol
+from llm_tool_cli.protocol.logic_cells.base import LogicCell
+from llm_tool_cli.protocol.logic_cells.journal import JournalCell
+from llm_tool_cli.protocol.output_cells.base import RenderContext
+
+
+class JournalCellFactory(Protocol):
+    __slots__ = ()
+
+    def __call__(self, *, message: str, actor_id: str | None) -> JournalCell: ...  # noqa: E704
+
+
+class OutputEmitter(Protocol):
+    __slots__ = ()
+
+    def emit(self, cells: list[LogicCell]) -> Result[None]: ...  # noqa: E704
+
+    def journal(self, message: str, *, actor_id: str | None | EllipsisType = ...) -> Result[None]: ...  # noqa: E704
+
+    def flush(self) -> None: ...  # noqa: E704
+
+    def discard(self) -> None:
+        """Discard pending ordinary results, retaining warnings for failure reporting."""
+        ...
+
+
+output = ContextValue[OutputEmitter]("output")
+
+
+class StreamOutputEmitter:
+    """Deliver journals now, then buffered results and warnings at finalization."""
+
+    __slots__ = ("_cells", "_warnings", "_stream", "_journal_failed", "journal_processor", "journal_factory")
+
+    def __init__(
+        self,
+        *,
+        stream: TextIO | None = None,
+        journal_processor: JournalProcessor | None = None,
+        journal_factory: JournalCellFactory = JournalCell,
+    ) -> None:
+        self._stream = stream
+        self.journal_processor = journal_processor if journal_processor is not None else NoopJournalProcessor()
+        self.journal_factory = journal_factory
+        # A processor failure disables forwarding for this emitter's lifetime.
+        self._journal_failed = False
+        self._cells: list[LogicCell] = []
+        self._warnings: list[LogicCell] = []
+
+    def journal(self, message: str, *, actor_id: str | None | EllipsisType = ...) -> Result[None]:
+        if actor_id is ...:
+            protocol = runtime_config.get().protocol
+            actor_id = "agent" if protocol == OutputProtocol.llm else protocol.value
+        return self.emit([self.journal_factory(message=message, actor_id=actor_id)])
+
+    @unwrap_to_error
+    def emit(self, cells: list[LogicCell]) -> Result[None]:  # noqa: CCR001
+        for cell in cells:
+            if cell.is_journal and not self._journal_failed:
+                processed = self.journal_processor.process(cell.to_journal_record())
+                if processed.is_err():
+                    self._journal_failed = True
+                    return processed
+            if cell.is_warning:
+                self._warnings.append(cell)
+            elif cell.is_journal:
+                self._write([cell])
+            else:
+                self._cells.append(cell)
+        return Ok(None)
+
+    def flush(self) -> None:
+        cells = [*self._cells, *self._warnings]
+        self._cells.clear()
+        self._warnings.clear()
+        self._write(cells)
+
+    def discard(self) -> None:
+        self._cells.clear()
+
+    def _write(self, cells: list[LogicCell]) -> None:
+        if not cells:
+            return
+        # Render the complete batch before writing so rendering failures cannot
+        # expose partial output. A failed stream write is not retried.
+        text = self._render(cells)
+        stream = self._stream if self._stream is not None else sys.stdout
+        stream.write(text)
+        stream.flush()
+
+    def _render(self, cells: list[LogicCell]) -> str:
+        """Prepare complete batch text; subclasses may override without handling streams."""
+        protocol = runtime_config.get().protocol
+        tool_label = settings.static_config.get().tool_label
+        sequence = [output_cell for cell in cells for output_cell in cell.render(protocol)]
+        return b"".join(
+            cell.render(RenderContext(index=index, total=len(sequence), tool_label=tool_label))
+            for index, cell in enumerate(sequence)
+        ).decode("utf-8")

llm_tool_cli/output/errors.py

@@ -0,0 +1,21 @@
+from llm_tool_cli.core.errors import EnvironmentError as BaseEnvironmentError
+
+
+class EnvironmentError(BaseEnvironmentError):
+    """Expected failures in output delivery."""
+
+
+class JournalCommandConfigInvalid(EnvironmentError):
+    code: str = "journal_command_config_invalid"
+    message: str = "Journal command config is invalid: {error.details}"
+    argument: str
+    details: str
+
+
+class JournalCommandFailed(EnvironmentError):
+    code: str = "journal_command_failed"
+    message: str = "Journal command failed: {error.details}"
+    ways_to_fix: list[str] = ["Check the configured journal command and its arguments."]
+    command: list[str]
+    returncode: int | None
+    details: str

llm_tool_cli/output/journal.py

@@ -0,0 +1,66 @@
+import subprocess  # noqa: S404
+from typing import Protocol
+
+import pydantic
+
+from llm_tool_cli.core.entities import BaseEntity
+from llm_tool_cli.core.result import Err, Ok, Result
+from llm_tool_cli.output.errors import JournalCommandConfigInvalid, JournalCommandFailed
+from llm_tool_cli.protocol.journal import JournalRecord
+
+
+class JournalProcessor(Protocol):
+    __slots__ = ()
+
+    def process(self, record: JournalRecord) -> Result[None]: ...  # noqa: E704
+
+
+class NoopJournalProcessor:
+    __slots__ = ()
+
+    def process(self, record: JournalRecord) -> Result[None]:
+        return Ok(None)
+
+
+class CommandJournalProcessor:
+    """Forward record fields as whole arguments, without a shell or text flattening."""
+
+    __slots__ = ("command",)
+
+    def __init__(self, command: list[str]) -> None:
+        self.command = tuple(command)
+
+    def process(self, record: JournalRecord) -> Result[None]:  # noqa: CCR001
+        if not self.command:
+            return Err([JournalCommandConfigInvalid(argument="", details="Configured command is empty.")])
+
+        fields = record.as_dict()
+        args = []
+        for argument in self.command:
+            if len(argument) >= 2 and argument.startswith("{") and argument.endswith("}"):
+                value = fields.get(argument[1:-1])
+                argument = "" if value is None else str(value)
+            args.append(argument)
+
+        try:
+            result = subprocess.run(args, check=False, capture_output=True, text=True)  # noqa: S603
+        except OSError as error:
+            return Err([JournalCommandFailed(command=args, returncode=None, details=str(error))])
+
+        if result.returncode:
+            details = f"exit code {result.returncode}"
+            if result.stderr.strip():
+                details += f"; stderr: {result.stderr.strip()}"
+            return Err([JournalCommandFailed(command=args, returncode=result.returncode, details=details)])
+        return Ok(None)
+
+
+class JournalConfig(BaseEntity):
+    """Optional external command forwarding."""
+
+    cmd: list[str] | None = pydantic.Field(default=None, min_length=1)
+
+    def processor(self) -> JournalProcessor:
+        if self.cmd is None:
+            return NoopJournalProcessor()
+        return CommandJournalProcessor(self.cmd)

llm_tool_cli/output/tests/helpers.py

@@ -0,0 +1,29 @@
+from llm_tool_cli.core.result import Ok, Result
+from llm_tool_cli.output import JournalCellFactory, StreamOutputEmitter, output
+from llm_tool_cli.protocol.logic_cells.base import LogicCell
+from llm_tool_cli.protocol.logic_cells.journal import JournalCell
+from llm_tool_cli.protocol.logic_cells.warning import WarningCell
+
+
+class CollectingEmitter(StreamOutputEmitter):
+    """Capture submitted logical cells without rendering or external side effects."""
+
+    def __init__(self, *, journal_factory: JournalCellFactory = JournalCell) -> None:
+        super().__init__(journal_factory=journal_factory)
+        self.cells: list[LogicCell] = []
+
+    def emit(self, cells: list[LogicCell]) -> Result[None]:
+        self.cells.extend(cells)
+        return Ok(None)
+
+    def flush(self) -> None:
+        pass
+
+    def discard(self) -> None:
+        self.cells = [cell for cell in self.cells if cell.is_warning]
+
+
+def warning_messages() -> list[str]:
+    emitter = output.get()
+    assert isinstance(emitter, CollectingEmitter)
+    return [cell.message for cell in emitter.cells if isinstance(cell, WarningCell)]