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

krons/agent/operations/act.py

@@ -0,0 +1,100 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Act operation: execute tool calls from LLM action requests.
+
+Handler signature: act(params, ctx) → list[ActionResponse]
+
+Supports sequential and concurrent execution strategies with
+rate-limiting via alcall (delay, throttle, max_concurrent).
+"""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import TYPE_CHECKING, Literal
+
+from krons.agent.message.action import ActionRequest, ActionResponse
+from krons.core.types import Params
+from krons.session.constraints import resource_must_be_accessible, resource_must_exist
+from krons.utils import alcall
+
+if TYPE_CHECKING:
+    from krons.resource.backend import Calling
+    from krons.session import Branch, Message, Session
+    from krons.work.operations import RequestContext
+
+
+class ActParams(Params):
+    """Parameters for tool execution.
+
+    Attributes:
+        action_requests: Messages with ActionRequest content to execute.
+        delay_before_start: Initial delay before first execution (seconds).
+        throttle_period: Delay between starting tasks (seconds).
+        max_concurrent: Concurrency limit (None = unlimited).
+        strategy: "concurrent" (default) or "sequential".
+    """
+
+    action_requests: list[Message]
+    delay_before_start: float = 0
+    throttle_period: float | None = None
+    max_concurrent: int | None = None
+    strategy: Literal["sequential", "concurrent"] = "concurrent"
+
+
+async def act(params: ActParams, ctx: RequestContext) -> list[ActionResponse]:
+    """Execute tool calls from action_requests."""
+    session = await ctx.get_session()
+    return await _act(session=session, branch=ctx.branch, **params.to_dict())
+
+
+async def _act(
+    action_requests: list[Message],
+    session: Session,
+    branch: Branch,
+    delay_before_start: float = 0,
+    throttle_period: float | None = None,
+    max_concurrent: int | None = None,
+    strategy: Literal["sequential", "concurrent"] = "concurrent",
+) -> list[ActionResponse]:
+    """Execute action requests against session-registered tools.
+
+    Validates resource existence and branch access before execution.
+    Returns ActionResponse per request (with result or error).
+    """
+    if not action_requests:
+        return []
+
+    # Validate all resources exist and are accessible before execution
+    for req in action_requests:
+        content: ActionRequest = req.content
+        resource_must_exist(session, content.function)
+        resource_must_be_accessible(branch, content.function)
+
+    async def _execute_one(req_msg: Message) -> ActionResponse:
+        """Execute a single action request and normalize result."""
+        action_request: ActionRequest = req_msg.content
+        calling: Calling = await session.request(
+            action_request.function, branch=branch, **action_request.arguments
+        )
+        try:
+            calling.assert_is_normalized()
+        except Exception as e:
+            return ActionResponse(
+                request_id=str(req_msg.id), error=f"ExecutionError: {e}"
+            )
+        return ActionResponse(request_id=str(req_msg.id), result=calling.response.data)
+
+    if strategy == "sequential":
+        results: list[ActionResponse] = []
+        for req_msg in action_requests:
+            results.append(await _execute_one(req_msg))
+        return results
+
+    return await partial(
+        alcall,
+        delay_before_start=delay_before_start,
+        throttle_period=throttle_period,
+        max_concurrent=max_concurrent,
+    )(action_requests, _execute_one)

krons/agent/operations/generate.py

@@ -0,0 +1,145 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Generate operation: stateless LLM call with message preparation.
+
+Handler signature: generate(params, ctx) → Calling | text | raw | Message
+Lowest-level operation — no message persistence, no validation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, JsonValue
+
+from krons.agent.message import Instruction, prepare_messages_for_chat
+from krons.core.types import ID, MaybeUnset, ModelConfig, Params, Unset
+from krons.errors import ConfigurationError
+from krons.session import Message, resource_must_be_accessible
+
+from ..message.common import CustomRenderer
+from .utils import ReturnAs, handle_return
+
+if TYPE_CHECKING:
+    from krons.resource import iModel
+    from krons.session import Branch, Session
+    from krons.work.operations import RequestContext
+
+__all__ = ("GenerateParams", "generate", "handle_return")
+
+
+@dataclass(frozen=True, slots=True)
+class GenerateParams(Params):
+    """Parameters for generate operation.
+
+    Provide either `instruction` (pre-built Message/Instruction) or
+    `primary` (string) to auto-build an Instruction via Instruction.create().
+
+    Attributes:
+        instruction: Pre-built Instruction or Message (takes priority).
+        primary: Instruction text (used when instruction is Unset).
+        context: Additional context merged into instruction.
+        imodel: Model name or iModel instance (Unset = session default).
+        return_as: How to unwrap the Calling result.
+        imodel_kwargs: Extra kwargs forwarded to imodel.invoke().
+    """
+
+    _config = ModelConfig(
+        sentinel_additions=frozenset({"none", "empty", "dataclass", "pydantic"})
+    )
+
+    instruction: MaybeUnset[Instruction | Message] = Unset
+    primary: MaybeUnset[str] = Unset
+    context: MaybeUnset[JsonValue] = Unset
+    imodel: MaybeUnset[iModel | str] = Unset
+    images: MaybeUnset[list[str]] = Unset
+    image_detail: MaybeUnset[Literal["low", "high", "auto"]] = Unset
+    tool_schemas: MaybeUnset[list[str]] = Unset
+    request_model: MaybeUnset[type[BaseModel]] = Unset
+    structure_format: Literal["json", "custom"] = "json"
+    custom_renderer: MaybeUnset[CustomRenderer] = Unset
+    return_as: ReturnAs = ReturnAs.CALLING
+    imodel_kwargs: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def instruction_message(self) -> Message:
+        """Resolve to a Message, building from primary if needed."""
+        if not self.is_sentinel_field("instruction"):
+            if isinstance(self.instruction, Message):
+                return self.instruction
+            if isinstance(self.instruction, Instruction):
+                return Message(content=self.instruction)
+
+        content = Instruction.create(
+            primary=self.primary,
+            context=self.context,
+            images=self.images,
+            image_detail=self.image_detail,
+            tool_schemas=self.tool_schemas,
+            request_model=self.request_model,
+            structure_format=self.structure_format,
+            custom_renderer=self.custom_renderer,
+        )
+        return Message(content=content)
+
+
+async def generate(params: GenerateParams, ctx: RequestContext) -> Any:
+    """Generate operation handler: resolve context and delegate to _generate."""
+    session = await ctx.get_session()
+    imodel = params.imodel if not params.is_sentinel_field("imodel") else None
+
+    # Propagate verbose from ctx to imodel_kwargs for streaming pretty-print
+    imodel_kwargs = dict(params.imodel_kwargs)
+    if ctx.metadata.get("_verbose"):
+        imodel_kwargs.setdefault("verbose", True)
+
+    return await _generate(
+        session=session,
+        branch=ctx.branch,
+        instruction=params.instruction_message,
+        imodel=imodel,
+        return_as=params.return_as,
+        **imodel_kwargs,
+    )
+
+
+async def _generate(
+    session: Session,
+    branch: Branch | str,
+    instruction: Message | Instruction | ID[Message],
+    imodel: iModel | str | None = None,
+    return_as: ReturnAs = ReturnAs.CALLING,
+    **imodel_kwargs: Any,
+) -> Any:
+    """Core generate: resolve model/branch/instruction → invoke → handle_return.
+
+    Args:
+        instruction: Message, Instruction, or message UUID to look up.
+        imodel: Model name (resolved from session.resources) or iModel instance.
+        return_as: Controls output unwrapping (see ReturnAs).
+        **imodel_kwargs: Forwarded to imodel.invoke().
+    """
+    if imodel is None:
+        imodel = session.default_gen_model
+    elif isinstance(imodel, str):
+        imodel = session.resources.get(imodel, None)
+    # else: already an iModel instance
+    if imodel is None:
+        raise ConfigurationError(
+            "Provided imodel could not be resolved, or no default model is set."
+        )
+
+    branch = session.get_branch(branch)
+    resource_must_be_accessible(branch, imodel.name)
+
+    if isinstance(instruction, UUID):
+        instruction = session.messages[instruction]
+    elif isinstance(instruction, Instruction):
+        instruction = Message(content=instruction)
+
+    prepared_msgs = prepare_messages_for_chat(session.messages, branch, instruction)
+    calling = await imodel.invoke(messages=prepared_msgs, **imodel_kwargs)
+    return handle_return(calling, return_as)

krons/agent/operations/llm_reparse.py

@@ -0,0 +1,89 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""LLM-assisted reparse: use a model to reformat malformed text into valid JSON.
+
+Called as a fallback when direct parse (regex/fuzzy) fails.
+Constructs an Instruction asking the model to extract structured data,
+then fuzzy-validates the result against target keys.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel
+
+from krons.agent.message import Instruction
+from krons.core.types import MaybeUnset, Unset, is_sentinel
+from krons.utils.fuzzy import HandleUnmatched, fuzzy_validate_mapping
+
+from ..message.common import CustomParser, CustomRenderer
+from .utils import ReturnAs
+
+if TYPE_CHECKING:
+    from krons.resource import iModel
+    from krons.session import Branch, Session
+
+__all__ = ("_llm_reparse",)
+
+PARSE_PROMPT = (
+    "Reformat text into specified model or structure, "
+    "using the provided schema format as a guide"
+)
+
+
+async def _llm_reparse(
+    session: Session,
+    branch: Branch,
+    text: str,
+    imodel: iModel | str,
+    tool_schemas: MaybeUnset[list[str]] = Unset,
+    request_model: MaybeUnset[type[BaseModel]] = Unset,
+    structure_format: MaybeUnset[Literal["json", "custom"]] = Unset,
+    custom_renderer: MaybeUnset[CustomRenderer] = Unset,
+    custom_parser: CustomParser | None = None,
+    fill_mapping: dict[str, Any] | None = None,
+    **imodel_kwargs: Any,
+) -> dict[str, Any]:
+    """Ask LLM to reformat text into structured JSON.
+
+    Builds an Instruction with the text as context and the target
+    schema from request_model, then generates and parses the result.
+
+    Returns:
+        Dict mapping target keys to extracted values.
+    """
+    instruction = Instruction.create(
+        primary=PARSE_PROMPT,
+        context=[{"text_to_format": text}],
+        request_model=request_model,
+        tool_schemas=tool_schemas,
+        structure_format=structure_format,
+        custom_renderer=custom_renderer,
+    )
+
+    from .generate import _generate
+
+    res = await _generate(
+        session=session,
+        branch=branch,
+        instruction=instruction,
+        imodel=imodel,
+        return_as=ReturnAs.TEXT,
+        **imodel_kwargs,
+    )
+
+    if is_sentinel(request_model, {"none", "empty"}):
+        raise ValueError("request_model is required for LLM reparse")
+    target_keys = list(request_model.model_fields.keys())
+
+    if custom_parser is not None:
+        return custom_parser(res, target_keys)
+
+    return fuzzy_validate_mapping(
+        res,
+        target_keys,
+        handle_unmatched=HandleUnmatched.FORCE,
+        fill_mapping=fill_mapping,
+    )

krons/agent/operations/operate.py

@@ -0,0 +1,247 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Operate: top-level agent operation chain.
+
+Handler signature: operate(params, ctx) -> validated model instance
+
+Full pipeline:
+  1. Compose request structure from operable (inject action spec if needed)
+  2. Structure: generate -> parse -> validate (produces typed model)
+  3. Act: extract and execute action_requests, persist messages
+  4. Compose response structure, merge action_results, validate
+
+Action spec injection:
+  If invoke_actions=True AND tool_schemas are present AND the branch
+  has "action" in its capabilities, the action_requests spec is injected
+  into the operable before composing the request structure. This lets
+  the LLM produce structured tool calls alongside regular output fields.
+
+Unlike lionagi's operate, krons does NOT allow runtime spec injection
+for arbitrary fields. Only the action spec is injected automatically
+based on explicit capability declarations.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal
+
+from krons.core.types import MaybeUnset, ModelConfig, Params, Unset
+from krons.session import Message
+
+from .act import ActParams, act
+from .generate import GenerateParams
+from .specs import Action, ActionResult, get_action_result_spec, get_action_spec
+from .structure import StructureParams, structure
+
+if TYPE_CHECKING:
+    from krons.agent.message.common import CustomParser
+    from krons.core.specs import Operable
+    from krons.resource import iModel
+    from krons.work.operations import RequestContext
+    from krons.work.rules.validator import Validator
+
+__all__ = ("OperateParams", "operate")
+
+
+@dataclass(frozen=True, slots=True)
+class OperateParams(Params):
+    """Parameters for operate (structure + act pipeline).
+
+    Flat parameter set — no nested StructureParams. The operate handler
+    builds StructureParams internally after runtime composition.
+
+    Attributes:
+        operable: Spec definition (required). Used to compose structures.
+        validator: Rule-based validator (required).
+        generate_params: LLM generation config.
+        request_model: Base model type for structured output.
+            If None, composed entirely from operable specs.
+        capabilities: Field subset for runtime composition.
+        invoke_actions: Enable action spec injection and execution.
+        action_strategy: "concurrent" (default) or "sequential".
+        max_concurrent: Concurrency limit for tool execution.
+        throttle_period: Delay between starting tool calls (seconds).
+        persist: Persist assistant/action messages to branch.
+    """
+
+    _config = ModelConfig(sentinel_additions=frozenset({"none", "empty"}))
+
+    # Required
+    operable: Operable
+    validator: Validator
+    generate_params: GenerateParams
+
+    # Structure composition
+    capabilities: set[str] | None = None
+    persist: bool = True
+
+    # Action stage
+    invoke_actions: bool = False
+    action_strategy: Literal["sequential", "concurrent"] = "concurrent"
+    max_concurrent: int | None = None
+    throttle_period: float | None = None
+
+    # Validation
+    auto_fix: bool = True
+    strict: bool = True
+
+    # Parse overrides
+    parse_imodel: MaybeUnset[iModel | str] = Unset
+    parse_imodel_kwargs: dict[str, Any] = field(default_factory=dict)
+    custom_parser: CustomParser | None = None
+    similarity_threshold: float = 0.85
+    max_retries: int = 3
+    fill_mapping: dict[str, Any] | None = None
+    fill_value: Any = Unset
+
+
+async def operate(params: OperateParams, ctx: RequestContext) -> Any:
+    """Operate handler: compose -> structure -> act -> merge.
+
+    Returns a validated model instance. If actions were invoked,
+    the response structure includes action_results.
+    """
+    session = await ctx.get_session()
+    branch = await ctx.get_branch()
+
+    operable = params.operable
+    gen_params = params.generate_params
+
+    # Determine if action spec should be injected
+    has_tools = not gen_params.is_sentinel_field("tool_schemas")
+    branch_caps = getattr(branch, "capabilities", set())
+    inject_actions = params.invoke_actions and has_tools and "action" in branch_caps
+
+    # --- Stage 1: Compose request structure ---
+    if inject_actions:
+        request_operable = operable.extend([get_action_spec()])
+    else:
+        request_operable = operable
+
+    request_structure = request_operable.compose_structure()
+
+    # Update generate params with the composed request model
+    use_gen_params = gen_params.with_updates(
+        copy_containers="deep", request_model=request_structure
+    )
+
+    # --- Stage 2: Structure (generate -> parse -> validate) ---
+    structure_params = StructureParams(
+        generate_params=use_gen_params,
+        validator=params.validator,
+        operable=request_operable,
+        structure=request_structure,
+        persist=params.persist,
+        capabilities=params.capabilities,
+        auto_fix=params.auto_fix,
+        strict=params.strict,
+        parse_imodel=params.parse_imodel,
+        parse_imodel_kwargs=params.parse_imodel_kwargs,
+        custom_parser=params.custom_parser,
+        similarity_threshold=params.similarity_threshold,
+        max_retries=params.max_retries,
+        fill_mapping=params.fill_mapping,
+        fill_value=params.fill_value,
+    )
+    structured = await structure(structure_params, ctx)
+
+    # --- Stage 3: Extract and execute actions ---
+    if not inject_actions:
+        return structured
+
+    act_requests = getattr(structured, "action_requests", None)
+    if not act_requests:
+        return structured
+
+    # Convert Action models to ActionRequest messages, persist to branch
+    action_messages = _actions_to_messages(act_requests)
+    if not action_messages:
+        return structured
+
+    for msg in action_messages:
+        session.add_message(msg, branches=branch)
+
+    act_params = ActParams(
+        action_requests=action_messages,
+        strategy=params.action_strategy,
+        max_concurrent=params.max_concurrent,
+        throttle_period=params.throttle_period,
+    )
+    action_responses = await act(act_params, ctx)
+
+    # Persist action response messages to branch
+    for resp in action_responses:
+        resp_msg = Message(content=resp)
+        session.add_message(resp_msg, branches=branch)
+
+    # Build ActionResult models from ActionResponse messages
+    action_results = _responses_to_results(action_responses, action_messages)
+
+    # --- Stage 4: Compose response structure, merge, return ---
+    # No re-validation needed: structured output was validated in stage 2,
+    # action_results are execution artifacts (not LLM output).
+    response_operable = request_operable.extend([get_action_result_spec()])
+    response_structure = response_operable.compose_structure()
+
+    data = request_operable.dump_instance(structured)
+    data["action_results"] = action_results
+
+    return response_structure(**data)
+
+
+def _actions_to_messages(act_requests: list) -> list[Message]:
+    """Convert Action models from structured output to ActionRequest Messages."""
+    from krons.agent.message.action import ActionRequest
+
+    messages: list[Message] = []
+    for req in act_requests:
+        if isinstance(req, Action):
+            content = ActionRequest.create(
+                function=req.function, arguments=req.arguments
+            )
+            messages.append(Message(content=content))
+        elif isinstance(req, dict):
+            content = ActionRequest.create(
+                function=req.get("function", ""),
+                arguments=req.get("arguments", {}),
+            )
+            messages.append(Message(content=content))
+    return messages
+
+
+def _responses_to_results(
+    action_responses: list,
+    action_messages: list[Message],
+) -> list[ActionResult]:
+    """Convert ActionResponse messages to ActionResult spec models.
+
+    Maps request_id back to function name via action_messages.
+    """
+    from krons.agent.message.action import ActionResponse
+
+    # Build request_id → function lookup from action messages
+    id_to_func: dict[str, str] = {}
+    for msg in action_messages:
+        content = msg.content
+        if hasattr(content, "function"):
+            id_to_func[str(msg.id)] = content.function
+
+    results: list[ActionResult] = []
+    for resp in action_responses:
+        if isinstance(resp, ActionResponse):
+            func = id_to_func.get(
+                resp.request_id if not resp._is_sentinel(resp.request_id) else "",
+                "",
+            )
+            results.append(
+                ActionResult(
+                    function=func,
+                    result=resp.result if resp.success else None,
+                    error=resp.error if not resp.success else None,
+                )
+            )
+        elif isinstance(resp, dict):
+            results.append(ActionResult.model_validate(resp))
+    return results