krons 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

krons/agent/message/__init__.py

@@ -0,0 +1,20 @@
+from .action import ActionRequest, ActionResponse
+from .assistant import Assistant
+from .common import CustomParser, CustomRenderer
+from .instruction import Instruction
+from .prepare_msg import prepare_messages_for_chat
+from .role import Role, RoledContent
+from .system import System
+
+__all__ = (
+    "ActionRequest",
+    "ActionResponse",
+    "Assistant",
+    "CustomParser",
+    "CustomRenderer",
+    "Instruction",
+    "Role",
+    "RoledContent",
+    "System",
+    "prepare_messages_for_chat",
+)

krons/agent/message/action.py

@@ -0,0 +1,69 @@
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+from krons.core.types import MaybeUnset, Unset
+from krons.utils.schemas import minimal_yaml
+
+from .role import Role, RoledContent
+
+
+@dataclass(slots=True)
+class ActionRequest(RoledContent):
+    """Action/function call request."""
+
+    role: ClassVar[Role] = Role.ACTION
+
+    function: MaybeUnset[str] = Unset
+    arguments: MaybeUnset[dict[str, Any]] = Unset
+
+    def render(self, *_args, **_kwargs) -> str:
+        doc: dict[str, Any] = {}
+        if not self._is_sentinel(self.function):
+            doc["function"] = self.function
+        doc["arguments"] = {} if self._is_sentinel(self.arguments) else self.arguments
+        return minimal_yaml(doc)
+
+    @classmethod
+    def create(cls, function: str, arguments: dict[str, Any] = Unset):
+        if cls._is_sentinel(arguments):
+            arguments = {}
+        return cls(function=function, arguments=arguments)
+
+
+@dataclass(slots=True)
+class ActionResponse(RoledContent):
+    """Function call response."""
+
+    role: ClassVar[Role] = Role.ACTION
+
+    request_id: MaybeUnset[str] = Unset
+    result: MaybeUnset[Any] = Unset
+    error: MaybeUnset[str] = Unset
+
+    def render(self, *_args, **_kwargs) -> str:
+        doc: dict[str, Any] = {"success": self.success}
+        if not self._is_sentinel(self.request_id):
+            doc["request_id"] = str(self.request_id)[:8]
+        if self.success:
+            if not self._is_sentinel(self.result):
+                doc["result"] = self.result
+        else:
+            doc["error"] = self.error
+        return minimal_yaml(doc)
+
+    @property
+    def success(self) -> bool:
+        return self._is_sentinel(self.error)
+
+    @classmethod
+    def create(
+        cls,
+        request_id: str | None = None,
+        result: Any = Unset,
+        error: str | None = None,
+    ) -> "ActionResponse":
+        return cls(
+            request_id=Unset if request_id is None else request_id,
+            result=result,
+            error=Unset if error is None else error,
+        )

krons/agent/message/assistant.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+from typing_extensions import Self
+
+from krons.core.types import MaybeUnset, Unset
+from krons.resource.backend import NormalizedResponse
+
+from .role import Role, RoledContent
+
+__all__ = (
+    "Assistant",
+    "parse_to_assistant_message",
+)
+
+
+@dataclass(slots=True)
+class Assistant(RoledContent):
+    """Assistant text response."""
+
+    role: ClassVar[Role] = Role.ASSISTANT
+    response: MaybeUnset[Any] = Unset
+
+    _buffered_response: Any = Unset
+
+    @classmethod
+    def create(cls, response_object: NormalizedResponse) -> Self:
+        self = cls(response=response_object.data)
+        self._buffered_response = response_object
+        return self
+
+    @property
+    def raw_response(self) -> dict[str, Any] | None:
+        if isinstance(self._buffered_response, NormalizedResponse):
+            return self._buffered_response.raw_response
+        return None
+
+    def render(self, *_args, **_kwargs) -> str:
+        return str(self.response) if not self.is_sentinel_field("response") else ""
+
+
+def parse_to_assistant_message(response: NormalizedResponse):
+    from krons.session.message import Message
+
+    metadata_dict: dict[str, Any] = {"raw_response": response.raw_response}
+    if response.metadata is not None:
+        metadata_dict.update(response.metadata)
+
+    return Message(
+        content=Assistant.create(response_object=response),
+        metadata=metadata_dict,
+    )

krons/agent/message/common.py

@@ -0,0 +1,49 @@
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from krons.core.types import Enum, MaybeUnset, Unset
+
+
+@runtime_checkable
+class CustomRenderer(Protocol):
+    """Protocol for custom instruction renderers.
+
+    Implementations format request_model schema for custom output formats.
+
+    Args:
+        model: Pydantic model class defining expected response schema
+        **kwargs: Additional renderer-specific options
+
+    Returns:
+        Formatted instruction string for the custom output format
+    """
+
+    def __call__(self, model: type[BaseModel], **kwargs: Any) -> str: ...
+
+
+@runtime_checkable
+class CustomParser(Protocol):
+    """Protocol for custom output parsers (e.g., LNDL).
+
+    Implementations extract structured data from LLM text responses.
+
+    Args:
+        text: Raw LLM response text
+        target_keys: Expected field names for fuzzy matching
+        **kwargs: Additional parser-specific options
+
+    Returns:
+        Dict mapping field names to extracted values
+    """
+
+    def __call__(
+        self, text: str, target_keys: list[str], **kwargs: Any
+    ) -> dict[str, Any]: ...
+
+
+class StructureFormat(Enum):
+    """Enumeration of structure formats for instruction rendering."""
+
+    JSON = "json"
+    CUSTOM = "custom"

krons/agent/message/instruction.py

@@ -0,0 +1,130 @@
+from dataclasses import dataclass
+from typing import Any, Callable, ClassVar, Literal
+
+from pydantic import BaseModel, JsonValue
+
+from krons.core.types import MaybeUnset, Unset
+from krons.resource.backend import is_unset
+from krons.utils.schemas import (
+    breakdown_pydantic_annotation,
+    format_clean_multiline_strings,
+    format_model_schema,
+    format_schema_pretty,
+    is_pydantic_model,
+    minimal_yaml,
+)
+
+from .common import CustomRenderer, StructureFormat
+from .role import Role, RoledContent
+
+
+@dataclass(slots=True)
+class Instruction(RoledContent):
+    role: ClassVar[Role] = Role.USER
+
+    primary: MaybeUnset[str] = Unset
+    context: MaybeUnset[list] = Unset
+    request_model: MaybeUnset[type[BaseModel]] = Unset
+    tool_schemas: MaybeUnset[list[str | dict]] = Unset
+    images: MaybeUnset[list[str]] = Unset
+    image_detail: MaybeUnset[Literal["low", "high", "auto"]] = Unset
+    structure_format: MaybeUnset[StructureFormat] = Unset
+    custom_renderer: MaybeUnset[Callable[[type[BaseModel]], str]] = Unset
+
+    @classmethod
+    def create(
+        cls,
+        primary: MaybeUnset[str] = Unset,
+        context: MaybeUnset[JsonValue] = Unset,
+        tool_schemas: MaybeUnset[list[str | dict]] = Unset,
+        request_model: MaybeUnset[type[BaseModel]] = Unset,
+        images: MaybeUnset[list[str]] = Unset,
+        image_detail: MaybeUnset[Literal["low", "high", "auto"]] = Unset,
+        structure_format: MaybeUnset[StructureFormat] = Unset,
+        custom_renderer: MaybeUnset[Callable[[type[BaseModel]], str]] = Unset,
+    ):
+        if is_unset(primary) and is_unset(request_model):
+            raise ValueError("Either 'primary' or 'request_model' must be provided.")
+
+        if not is_unset(request_model) and not is_pydantic_model(request_model):
+            raise ValueError(
+                "'request_model' must be a subclass of pydantic BaseModel."
+            )
+
+        if not is_unset(images) and images is not None:
+            from krons.utils.validators import validate_image_url
+
+            for url in images:
+                validate_image_url(url)
+
+        if not cls._is_sentinel(context):
+            context = [context] if not isinstance(context, list) else context
+
+        return cls(
+            primary=primary,
+            context=context,
+            tool_schemas=tool_schemas,
+            request_model=request_model,
+            images=images,
+            image_detail=image_detail,
+            structure_format=structure_format,
+            custom_renderer=custom_renderer,
+        )
+
+    def _format_text_content(
+        self,
+        structure_format: StructureFormat,
+        custom_renderer: MaybeUnset[CustomRenderer],
+    ) -> str:
+        if structure_format == StructureFormat.CUSTOM and not callable(custom_renderer):
+            raise ValueError(
+                "Custom renderer must be provided when structure_format is 'custom'."
+            )
+
+        task_data = {
+            "Primary Instruction": self.primary,
+            "Context": self.context,
+            "Tools": self.tool_schemas,
+        }
+        text = _format_task(
+            {k: v for k, v in task_data.items() if not self._is_sentinel(v)}
+        )
+
+        if not self._is_sentinel(self.request_model):
+            model = self.request_model
+            text += format_model_schema(model)
+
+            if structure_format == StructureFormat.CUSTOM:
+                text += custom_renderer(model)
+            elif structure_format == StructureFormat.JSON or is_unset(structure_format):
+                text += _format_json_response_structure(model)
+
+        return text.strip()
+
+    def render(
+        self, structure_format=Unset, custom_renderer=Unset
+    ) -> str | list[dict[str, Any]]:
+        structure_format = (
+            self.structure_format if is_unset(structure_format) else structure_format
+        )
+        custom_renderer = (
+            self.custom_renderer if is_unset(custom_renderer) else custom_renderer
+        )
+        text = self._format_text_content(structure_format, custom_renderer)
+        return text if is_unset(self.images) else self._format_image_content(text)
+
+
+def _format_json_response_structure(request_model: type[BaseModel]) -> str:
+    """Format response structure with Python types (unquoted)."""
+    schema = breakdown_pydantic_annotation(request_model)
+    json_schema = "\n\n## ResponseFormat\n"
+    json_schema += "```json\n"
+    json_schema += format_schema_pretty(schema, indent=0)
+    json_schema += "\n```\nMUST RETURN VALID JSON. USER's SUCCESS DEPENDS ON IT. Return ONLY valid JSON without markdown code blocks.\n"
+    return json_schema
+
+
+def _format_task(task_data: dict) -> str:
+    text = "## Task\n"
+    text += minimal_yaml(format_clean_multiline_strings(task_data))
+    return text

krons/agent/message/prepare_msg.py

@@ -0,0 +1,187 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from pydantic import JsonValue
+
+from krons.core import Pile, Progression
+from krons.session import Message
+
+from .action import ActionResponse
+from .assistant import Assistant
+from .instruction import Instruction
+from .role import RoledContent
+from .system import System
+
+__all__ = ("prepare_messages_for_chat",)
+
+
+def _get_text(content: RoledContent, attr: str) -> str:
+    """Get text from content attr, returning '' if sentinel."""
+    val = getattr(content, attr)
+    return "" if content._is_sentinel(val) else val
+
+
+def _build_context(content: Instruction, action_outputs: list[str]) -> list[JsonValue]:
+    """Build context list by appending action outputs to existing context."""
+    existing = content.context
+    if content._is_sentinel(existing):
+        return cast(list[JsonValue], list(action_outputs))
+    return cast(list[JsonValue], list(cast(list[JsonValue], existing)) + action_outputs)
+
+
+def prepare_messages_for_chat(
+    messages: Pile[Message],
+    progression: Progression | None = None,
+    new_instruction: Message | Instruction | None = None,
+    to_chat: bool = True,
+) -> list[RoledContent] | list[dict[str, Any]]:
+    """Prepare messages for chat API with intelligent content organization.
+
+    Algorithm:
+    1. Auto-detect system message from first message (if SystemContent)
+    2. Collect ActionResponseContent and embed into following instruction's context
+    3. Merge consecutive AssistantResponses
+    4. Embed system into first instruction
+    5. Append new_instruction
+
+    Args:
+        messages: Pile of messages
+        progression: Progression or list of UUIDs (None = all messages)
+        new_instruction: New instruction to append
+        to_chat: If True, return list[dict] chat format instead of MessageContent
+
+    Returns:
+        List of prepared MessageContent instances (immutable copies), or
+        List of chat API dicts if to_chat=True
+    """
+    to_use: Pile[Message] = messages if progression is None else messages[progression]
+
+    if len(to_use) == 0:
+        if new_instruction:
+            new_content = (
+                new_instruction.content
+                if isinstance(new_instruction, Message)
+                else new_instruction
+            )
+            new_content: Instruction = new_content.with_updates(copy_containers="deep")
+            if to_chat:
+                chat_msg = {
+                    "role": new_content.role.value,
+                    "content": new_content.render(
+                        new_content.structure_format, new_content.custom_renderer
+                    ),
+                }
+                if chat_msg and chat_msg.get("content"):
+                    return [chat_msg]
+                return []
+            return [new_content]
+        return []
+
+    # Phase 1: Extract system message (auto-detect from first message)
+    system_text: str | None = None
+    start_idx = 0
+
+    first_msg = to_use[0]
+    if isinstance(first_msg.content, System):
+        system_text = first_msg.content.render()
+        start_idx = 1
+
+    # Phase 2: Process messages - collect action outputs for next instruction
+    _use_msgs: list[RoledContent] = []
+    pending_actions: list[str] = []
+
+    for i, msg in enumerate(to_use):
+        if i < start_idx:
+            continue
+
+        content: RoledContent = msg.content
+
+        # ActionResponseContent: collect rendered output
+        if isinstance(content, ActionResponse):
+            pending_actions.append(content.render())
+            continue
+
+        # SystemContent in middle: skip
+        if isinstance(content, System):
+            continue
+
+        # InstructionContent: embed pending action outputs
+        if isinstance(content, Instruction):
+            updates: dict[str, Any] = {"tool_schemas": None, "request_model": None}
+            if pending_actions:
+                updates["context"] = _build_context(content, pending_actions)
+                pending_actions = []
+            _use_msgs.append(content.with_updates(copy_containers="deep", **updates))
+            continue
+
+        # Other (AssistantResponse, ActionRequest): copy as-is
+        _use_msgs.append(content.with_updates(copy_containers="deep"))
+
+    # Phase 3: Merge consecutive AssistantResponses
+    if len(_use_msgs) > 1:
+        merged: list[RoledContent] = [_use_msgs[0]]
+        for content in _use_msgs[1:]:
+            if isinstance(content, Assistant) and isinstance(merged[-1], Assistant):
+                prev = _get_text(merged[-1], "assistant_response")
+                curr = _get_text(content, "assistant_response")
+                merged[-1] = Assistant.create(assistant_response=f"{prev}\n\n{curr}")
+            else:
+                merged.append(content)
+        _use_msgs = merged
+
+    # Phase 4: Embed system message into first instruction
+    if system_text:
+        if len(_use_msgs) == 0 and new_instruction:
+            # No history: embed into new_instruction
+            if isinstance(new_instruction.content, Instruction):
+                curr = _get_text(new_instruction.content, "primary")
+                system_updates: dict[str, Any] = {"primary": f"{system_text}\n\n{curr}"}
+                if pending_actions:
+                    system_updates["context"] = _build_context(
+                        new_instruction.content, pending_actions
+                    )
+                    pending_actions = []
+                _use_msgs.append(
+                    new_instruction.content.with_updates(
+                        copy_containers="deep", **system_updates
+                    )
+                )
+                new_instruction = None
+        elif _use_msgs and isinstance(_use_msgs[0], Instruction):
+            curr = _get_text(_use_msgs[0], "primary")
+            _use_msgs[0] = _use_msgs[0].with_updates(primary=f"{system_text}\n\n{curr}")
+
+    # Phase 5: Append new_instruction (with any remaining action outputs)
+    if new_instruction:
+        final_updates: dict[str, Any] = {}
+        if pending_actions and isinstance(new_instruction.content, Instruction):
+            final_updates["context"] = _build_context(
+                new_instruction.content, pending_actions
+            )
+        _use_msgs.append(
+            new_instruction.content.with_updates(
+                copy_containers="deep", **final_updates
+            )
+        )
+
+    if to_chat:
+        result = []
+        for m in _use_msgs:
+            data = {}
+            if isinstance(m, Instruction):
+                data = {
+                    "structure_format": m.structure_format,
+                    "custom_renderer": m.custom_renderer,
+                }
+
+            result.append(
+                {
+                    "role": m.role.value,
+                    "content": m.render(**data),
+                }
+            )
+        return result
+    return _use_msgs

krons/agent/message/role.py

@@ -0,0 +1,53 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+
+from __future__ import annotations
+
+import logging
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+from krons.core.types import DataClass, Enum, ModelConfig
+from krons.protocols import Deserializable, implements
+
+logger = logging.getLogger(__name__)
+
+
+class Role(Enum):
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    ACTION = "action"
+    UNSET = "unset"
+
+
+@implements(Deserializable)
+@dataclass(slots=True)
+class RoledContent(DataClass):
+    _config: ClassVar[ModelConfig] = ModelConfig(
+        sentinel_additions=frozenset({"none", "empty"}),
+        use_enum_values=True,
+    )
+
+    role: Role = Role.UNSET
+
+    @classmethod
+    @abstractmethod
+    def create(cls, **kwargs) -> RoledContent:
+        raise NotImplementedError("Subclasses must implement create method")
+
+    @abstractmethod
+    def render(self, *args, **kwargs) -> str:
+        raise NotImplementedError("Subclasses must implement render method")
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], **kwargs: Any) -> RoledContent:
+        return cls.create(
+            **{
+                k: v
+                for k in cls.allowed()
+                if (k in data and not cls._is_sentinel(v := data[k]))
+            }
+        )

krons/agent/message/system.py

@@ -0,0 +1,53 @@
+from dataclasses import dataclass
+from typing import Callable, ClassVar, Literal
+
+from krons.core.types import MaybeUnset, Unset
+from krons.utils import now_utc
+
+from .role import Role, RoledContent
+
+
+@dataclass(slots=True)
+class System(RoledContent):
+    """System message with optional timestamp."""
+
+    role: ClassVar[Role] = Role.SYSTEM
+
+    system_message: MaybeUnset[str] = Unset
+    system_datetime: MaybeUnset[str | Literal[True]] = Unset
+    datetime_factory: MaybeUnset[Callable[[], str]] = Unset
+
+    def render(self, *_args, **_kwargs) -> str:
+        parts: list[str] = []
+        if not self._is_sentinel(self.system_datetime):
+            timestamp = (
+                now_utc().isoformat(timespec="seconds")
+                if self.system_datetime is True
+                else self.system_datetime
+            )
+            parts.append(f"System Time: {timestamp}")
+        elif not self._is_sentinel(self.datetime_factory):
+            factory = self.datetime_factory
+            parts.append(f"System Time: {factory()}")
+
+        if not self._is_sentinel(self.system_message):
+            parts.append(self.system_message)
+
+        return "\n\n".join(parts)
+
+    @classmethod
+    def create(
+        cls,
+        system_message: str | None = None,
+        system_datetime: str | Literal[True] | None = None,
+        datetime_factory: Callable[[], str] | None = None,
+    ) -> "System":
+        if not cls._is_sentinel(system_datetime) and not cls._is_sentinel(
+            datetime_factory
+        ):
+            raise ValueError("Cannot set both system_datetime and datetime_factory")
+        return cls(
+            system_message=Unset if system_message is None else system_message,
+            system_datetime=Unset if system_datetime is None else system_datetime,
+            datetime_factory=Unset if datetime_factory is None else datetime_factory,
+        )

krons/agent/operations/__init__.py

@@ -0,0 +1,82 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent operations: composable LLM pipeline stages.
+
+Handlers (async handler(params, ctx) -> result):
+    generate: Stateless LLM call with message preparation.
+    parse: JSON extraction with LLM reparse fallback.
+    structure: generate -> parse -> validate pipeline.
+    operate: structure + action execution + response composition.
+    act: Tool/action execution from structured output.
+    react / react_stream: Multi-round reason-act loop.
+
+Spec models:
+    Action, ActionResult: Tool call request/result models.
+    Instruct: Task handoff bundle for orchestration.
+    ReActAnalysis, PlannedAction, Analysis: ReAct loop models.
+
+Built-in handlers are auto-registered on Session creation:
+    generate, structure, operate, react, react_stream
+
+Usage:
+    result = await session.conduct("operate", branch, params)
+    async for analysis in session.stream_conduct("react_stream", params=...):
+        print(analysis)
+"""
+
+from __future__ import annotations
+
+from .act import ActParams, act
+from .generate import GenerateParams, generate
+from .operate import OperateParams, operate
+from .parse import ParseParams, parse
+from .react import (
+    Analysis,
+    PlannedAction,
+    ReActAnalysis,
+    ReActParams,
+    react,
+    react_stream,
+)
+from .specs import (
+    Action,
+    ActionResult,
+    Instruct,
+    get_action_result_spec,
+    get_action_spec,
+    get_instruct_spec,
+)
+from .structure import StructureParams, structure
+from .utils import ReturnAs
+
+__all__ = (
+    # Handlers
+    "act",
+    "generate",
+    "operate",
+    "parse",
+    "react",
+    "react_stream",
+    "structure",
+    # Params
+    "ActParams",
+    "GenerateParams",
+    "OperateParams",
+    "ParseParams",
+    "ReActParams",
+    "StructureParams",
+    # Spec models
+    "Action",
+    "ActionResult",
+    "Analysis",
+    "Instruct",
+    "PlannedAction",
+    "ReActAnalysis",
+    # Spec factories
+    "get_action_result_spec",
+    "get_action_spec",
+    "get_instruct_spec",
+    # Utils
+    "ReturnAs",
+)