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

krons/agent/operations/specs.py

@@ -0,0 +1,235 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Specs for agent operations.
+
+Action: validated tool-call request model (function + arguments).
+ActionResult: validated tool-call result model (function, result, error).
+get_action_spec / get_action_result_spec: Spec factories for
+runtime operable composition in operate.
+"""
+
+from __future__ import annotations
+
+import re
+from functools import cache
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, JsonValue, field_validator
+
+from krons.core.types import HashableModel
+from krons.utils import extract_json, to_dict, to_list
+
+__all__ = (
+    "Action",
+    "ActionResult",
+    "Instruct",
+    "get_action_spec",
+    "get_action_result_spec",
+    "get_instruct_spec",
+)
+
+
+class Action(HashableModel):
+    """Validated tool/action request: (function, arguments) pair.
+
+    Parsed from LLM output via fuzzy JSON extraction.
+    """
+
+    function: str = Field(
+        description=(
+            "Function name from tool_schemas. "
+            "Never invent names outside provided schemas."
+        ),
+    )
+    arguments: dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Argument dict for the function. Use only names/types from tool_schemas."
+        ),
+    )
+
+    @field_validator("arguments", mode="before")
+    @classmethod
+    def _coerce_arguments(cls, value: Any) -> dict[str, Any]:
+        """Coerce arguments into a dict, handling JSON strings."""
+        if isinstance(value, dict):
+            return value
+        return to_dict(
+            value,
+            fuzzy_parse=True,
+            recursive=True,
+            recursive_python_only=False,
+        )
+
+    @classmethod
+    def create(cls, content: str | dict | BaseModel) -> list[Action]:
+        """Parse raw LLM output into Action instances. Returns [] on failure."""
+        try:
+            parsed = _parse_action_blocks(content)
+            return [cls.model_validate(item) for item in parsed] if parsed else []
+        except Exception:
+            return []
+
+
+class ActionResult(HashableModel):
+    """Validated tool-call result: (function, result, error) triple.
+
+    Produced by act stage after executing Action requests.
+    """
+
+    function: str = Field(description="Function name that was called.")
+    result: Any = Field(default=None, description="Return value on success.")
+    error: str | None = Field(default=None, description="Error message on failure.")
+
+    @property
+    def success(self) -> bool:
+        return self.error is None
+
+
+class Instruct(HashableModel):
+    """Instruction bundle for orchestrated task handoff.
+
+    Encapsulates everything needed to hand off a task: what to do,
+    strategic guidance, background context, and execution preferences.
+    Used as a structured handoff between orchestrator and workers.
+    """
+
+    instruction: str | None = Field(
+        default=None,
+        description=(
+            "Clear, actionable task definition. Specify the primary goal, "
+            "key constraints, and success criteria."
+        ),
+    )
+    guidance: JsonValue | None = Field(
+        default=None,
+        description=(
+            "Strategic direction: preferred methods, quality benchmarks, "
+            "resource constraints, or compliance requirements."
+        ),
+    )
+    context: JsonValue | None = Field(
+        default=None,
+        description=(
+            "Background information directly relevant to the task: "
+            "environment, prior outcomes, system states, or dependencies."
+        ),
+    )
+    reason: bool = Field(
+        default=False,
+        description=(
+            "Include reasoning: explanations of decisions, trade-offs, "
+            "alternatives considered, and confidence assessment."
+        ),
+    )
+    actions: bool = Field(
+        default=False,
+        description=(
+            "Enable action execution via tool_schemas. "
+            "True: execute tool calls. False: analysis only."
+        ),
+    )
+    action_strategy: Literal["sequential", "concurrent"] = Field(
+        default="concurrent",
+        description="How to execute actions: sequential or concurrent.",
+    )
+
+    @field_validator("action_strategy", mode="before")
+    @classmethod
+    def _validate_action_strategy(cls, v: Any) -> str:
+        if v not in ("sequential", "concurrent"):
+            return "concurrent"
+        return v
+
+
+@cache
+def get_instruct_spec():
+    """Spec for instruct_model: Instruct | None."""
+    from krons.core.specs import Spec
+
+    return Spec(Instruct, name="instruct_model").as_nullable()
+
+
+@cache
+def get_action_spec():
+    """Spec for action_requests: list[Action] | None."""
+    from krons.core.specs import Spec
+
+    return Spec(Action, name="action_requests").as_listable().as_nullable()
+
+
+@cache
+def get_action_result_spec():
+    """Spec for action_results: list[ActionResult] | None."""
+    from krons.core.specs import Spec
+
+    return Spec(ActionResult, name="action_results").as_listable().as_nullable()
+
+
+# ---------------------------------------------------------------------------
+# Parsing helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_action_blocks(content: str | dict | BaseModel) -> list[dict]:
+    """Extract action request dicts from raw content.
+
+    Normalizes provider-specific key names to {function, arguments}.
+    """
+    json_blocks: list = []
+
+    if isinstance(content, BaseModel):
+        json_blocks = [content.model_dump()]
+    elif isinstance(content, str):
+        json_blocks = extract_json(content, fuzzy_parse=True)
+        if not json_blocks:
+            # Fallback: try extracting from ```python ... ``` blocks
+            matches = re.findall(r"```python\s*(.*?)\s*```", content, re.DOTALL)
+            json_blocks = to_list(
+                [extract_json(m, fuzzy_parse=True) for m in matches],
+                dropna=True,
+            )
+    elif isinstance(content, dict):
+        json_blocks = [content]
+
+    if json_blocks and not isinstance(json_blocks, list):
+        json_blocks = [json_blocks]
+
+    out: list[dict] = []
+    for block in json_blocks:
+        if not isinstance(block, dict):
+            continue
+        normalized = _normalize_action_keys(block)
+        if normalized:
+            out.append(normalized)
+    return out
+
+
+def _normalize_action_keys(d: dict) -> dict | None:
+    """Map provider-specific key names to canonical {function, arguments}.
+
+    Returns None if required keys are missing.
+    """
+    result: dict[str, Any] = {}
+
+    # Handle nested function.name pattern
+    if "function" in d and isinstance(d["function"], dict) and "name" in d["function"]:
+        d = {**d, "function": d["function"]["name"]}
+
+    for k, v in d.items():
+        # Strip common prefixes: action_name → name, recipient_name → name
+        normalized = (
+            k.replace("action_", "").replace("recipient_", "").removesuffix("s")
+        )
+        if normalized in ("name", "function", "recipient"):
+            result["function"] = v
+        elif normalized in ("parameter", "argument", "arg", "param"):
+            result["arguments"] = to_dict(
+                v, str_type="json", fuzzy_parse=True, suppress=True
+            )
+
+    if "function" in result:
+        result.setdefault("arguments", {})
+        return result
+    return None

krons/agent/operations/structure.py

@@ -0,0 +1,151 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Structure operation: generate -> parse -> validate pipeline.
+
+Handler signature: structure(params, ctx) -> validated dict or model instance
+
+Three-stage pipeline:
+  1. generate: LLM call (TEXT or MESSAGE depending on persist)
+  2. parse: extract JSON from text (direct + LLM reparse fallback)
+  3. validate: enforce operable specs + cast to composed structure
+
+When persist=True, the assistant message is stored in the branch
+before parsing. The text is extracted from message.content.response.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+from krons.core.types import MaybeUnset, ModelConfig, Params, Unset, is_unset
+
+from .generate import GenerateParams, generate
+from .parse import ParseParams, parse
+from .utils import ReturnAs
+
+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__ = ("StructureParams", "structure")
+
+
+@dataclass(frozen=True, slots=True)
+class StructureParams(Params):
+    """Parameters for structure operation (generate -> parse -> validate).
+
+    Attributes:
+        generate_params: LLM generation config.
+        validator: Rule-based validator for operable spec enforcement.
+        operable: Spec definition for field validation (required).
+        structure: Pre-composed Pydantic model to cast into.
+            If None, auto-composed from operable via compose_structure().
+        persist: Persist assistant message to branch before parsing.
+        capabilities: Allowed field subset (None = all operable fields).
+        auto_fix: Auto-coerce validation issues (e.g., wrap scalar -> list).
+        strict: Raise on validation failure vs. skip.
+    """
+
+    _config = ModelConfig(sentinel_additions=frozenset({"none", "empty"}))
+
+    # Generate stage
+    generate_params: GenerateParams
+
+    # Validate stage
+    validator: Validator
+    operable: Operable
+    structure: type[BaseModel] | None = None
+    capabilities: set[str] | None = None
+    auto_fix: bool = True
+    strict: bool = True
+
+    # Message persistence
+    persist: bool = False
+
+    # Parse stage 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 structure(params: StructureParams, ctx: RequestContext) -> Any:
+    """Structure operation handler: generate -> parse -> validate.
+
+    When persist=True, generates as MESSAGE, persists to branch,
+    then extracts text from message.content.response for parsing.
+    """
+    # Resolve structure type: explicit or auto-composed from operable
+    structure_type = params.structure
+    if structure_type is None:
+        structure_type = params.operable.compose_structure()
+
+    # Stage 1: Generate
+    if params.persist:
+        text = await _generate_and_persist(params.generate_params, ctx)
+    else:
+        gen_params = params.generate_params.with_updates(
+            copy_containers="deep", return_as=ReturnAs.TEXT
+        )
+        text = await generate(gen_params, ctx)
+
+    # Stage 2: Parse (inherit schema config from generate params)
+    gen = params.generate_params
+    parse_params = ParseParams(
+        text=text,
+        imodel=params.parse_imodel if not is_unset(params.parse_imodel) else None,
+        imodel_kwargs=params.parse_imodel_kwargs or {},
+        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,
+        request_model=gen.request_model,
+        tool_schemas=gen.tool_schemas,
+        structure_format=gen.structure_format,
+        custom_renderer=gen.custom_renderer,
+    )
+    parsed = await parse(parse_params, ctx)
+
+    # Stage 3: Validate against operable specs + structure type
+    return await params.validator.validate(
+        parsed,
+        params.operable,
+        capabilities=params.capabilities,
+        auto_fix=params.auto_fix,
+        strict=params.strict,
+        structure=structure_type,
+    )
+
+
+async def _generate_and_persist(
+    generate_params: GenerateParams,
+    ctx: RequestContext,
+) -> str:
+    """Generate as MESSAGE, persist to branch, return text.
+
+    The assistant message is added to both session messages and
+    the branch progression for conversation continuity.
+    """
+    gen_params = generate_params.with_updates(
+        copy_containers="deep", return_as=ReturnAs.MESSAGE
+    )
+    message = await generate(gen_params, ctx)
+
+    # Persist to branch
+    session = await ctx.get_session()
+    branch = await ctx.get_branch()
+    session.add_message(message, branches=branch)
+
+    # Extract text from assistant content
+    return message.content.response

krons/agent/operations/utils.py

@@ -0,0 +1,79 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared utilities for agent operations.
+
+ReturnAs: Enum controlling how Calling results are unwrapped.
+handle_return: Dispatch Calling → desired output form.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from krons.core.types import Enum, MaybeUnset, Unset, is_sentinel
+from krons.errors import ValidationError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from krons.resource.backend import Calling
+
+
+class ReturnAs(Enum):
+    """How to unwrap a Calling result.
+
+    TEXT      - response.data (typically the LLM text)
+    RAW       - response.raw_response (provider-specific dict)
+    RESPONSE  - the NormalizedResponse object
+    MESSAGE   - wrapped as a Message with Assistant content
+    CALLING   - the raw Calling event (no unwrap, no validation)
+    CUSTOM    - apply caller-supplied return_parser
+    """
+
+    TEXT = "text"
+    RAW = "raw"
+    RESPONSE = "response"
+    MESSAGE = "message"
+    CALLING = "calling"
+    CUSTOM = "custom"
+
+
+def handle_return(
+    calling: Calling,
+    return_as: ReturnAs,
+    /,
+    *,
+    return_parser: MaybeUnset[Callable] = Unset,
+):
+    """Unwrap a Calling into the form requested by return_as.
+
+    CALLING and CUSTOM bypass normalization checks.
+    All other modes call calling.assert_is_normalized() first.
+    """
+    if return_as == ReturnAs.CALLING:
+        return calling
+
+    if return_as == ReturnAs.CUSTOM:
+        if is_sentinel(return_parser, {"none", "empty"}) or not callable(return_parser):
+            raise ValidationError(
+                "return_parser must be provided as a callable when return_as is 'custom'"
+            )
+        return return_parser(calling)
+
+    calling.assert_is_normalized()
+    response = calling.response
+
+    match return_as:
+        case ReturnAs.TEXT:
+            return response.data
+        case ReturnAs.RAW:
+            return response.raw_response
+        case ReturnAs.RESPONSE:
+            return response
+        case ReturnAs.MESSAGE:
+            from krons.agent.message.assistant import parse_to_assistant_message
+
+            return parse_to_assistant_message(response)
+        case _:
+            raise ValidationError(f"Unsupported return_as: {return_as.value}")

krons/agent/providers/__init__.py

@@ -0,0 +1,17 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from .anthropic_messages import AnthropicMessagesEndpoint, create_anthropic_config
+from .gemini import GeminiCodeEndpoint, create_gemini_code_config
+from .match import match_endpoint
+from .oai_chat import OAIChatEndpoint, create_oai_chat
+
+__all__ = (
+    "AnthropicMessagesEndpoint",
+    "GeminiCodeEndpoint",
+    "OAIChatEndpoint",
+    "create_anthropic_config",
+    "create_gemini_code_config",
+    "create_oai_chat",
+    "match_endpoint",
+)

krons/agent/providers/anthropic_messages.py

@@ -0,0 +1,146 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Any
+
+from krons.resource.backend import NormalizedResponseModel
+from krons.resource.endpoint import Endpoint, EndpointConfig
+
+__all__ = (
+    "AnthropicMessagesEndpoint",
+    "create_anthropic_config",
+)
+
+
+def create_anthropic_config(
+    name: str = "anthropic_messages",
+    api_key: str | None = None,
+    base_url: str = "https://api.anthropic.com/v1",
+    endpoint: str = "messages",
+    anthropic_version: str = "2023-06-01",
+) -> dict:
+    """Factory for Anthropic Messages API config.
+
+    Args:
+        api_key: API key or env var name (default: "ANTHROPIC_API_KEY")
+        base_url: Base API URL
+        endpoint: Endpoint path
+        anthropic_version: API version header
+
+    Returns:
+        Config dict
+
+    Example:
+        >>> config = create_anthropic_config()
+        >>> endpoint = AnthropicMessagesEndpoint(config=config)
+        >>> response = await endpoint.call(
+        ...     {"model": "claude-sonnet-4-5-20250929", "messages": [...]}
+        ... )
+    """
+    if api_key is None:
+        api_key = "ANTHROPIC_API_KEY"
+
+    return {
+        "name": name,
+        "provider": "anthropic",
+        "base_url": base_url,
+        "endpoint": endpoint,
+        "api_key": api_key,
+        "auth_type": "x-api-key",
+        "default_headers": {"anthropic-version": anthropic_version},
+    }
+
+
+class AnthropicMessagesEndpoint(Endpoint):
+    """Anthropic Messages API endpoint.
+
+    Supports Anthropic-specific response normalization.
+
+    Usage:
+        endpoint = AnthropicMessagesEndpoint()
+        response = await endpoint.call({
+            "model": "claude-sonnet-4-5-20250929",
+            "messages": [{"role": "user", "content": "Hello"}],
+            "max_tokens": 1024
+        })
+    """
+
+    def __init__(
+        self,
+        config: dict | EndpointConfig | None = None,
+        circuit_breaker: Any | None = None,
+        **kwargs,
+    ):
+        """Initialize with Anthropic config."""
+        if config is None:
+            config = create_anthropic_config(**kwargs)
+        elif isinstance(config, EndpointConfig):
+            config = config.model_dump()
+        if not isinstance(config, dict):
+            raise ValueError(
+                "Provided config must be a dict or EndpointConfig instance"
+            )
+
+        # Ensure request_options is set
+        if config.get("request_options") is None:
+            from ..third_party.anthropic_models import CreateMessageRequest
+
+            config["request_options"] = CreateMessageRequest
+
+        super().__init__(config=config, circuit_breaker=circuit_breaker, **kwargs)
+
+    def normalize_response(self, response: dict[str, Any]) -> NormalizedResponseModel:
+        """Normalize Anthropic response to standard format.
+
+        Extracts:
+        - Text from content blocks
+        - Thinking blocks (if extended thinking enabled)
+        - Usage stats
+        - Stop reason
+        - Model info
+        - Tool uses
+        """
+        # Extract text and thinking from content blocks
+        text_parts = []
+        thinking_parts = []
+
+        content = response.get("content")
+        if content:
+            for block in content:
+                block_type = block.get("type")
+                if block_type == "text":
+                    text_parts.append(block.get("text", ""))
+                elif block_type == "thinking":
+                    thinking_parts.append(block.get("thinking", ""))
+
+        # Combine text
+        text = "\n\n".join(text_parts)
+
+        # Extract metadata
+        metadata: dict[str, Any] = {
+            k: response[k]
+            for k in ("model", "usage", "stop_reason", "stop_sequence", "id")
+            if k in response
+        }
+
+        # Add thinking if present
+        if thinking_parts:
+            metadata["thinking"] = "\n\n".join(thinking_parts)
+
+        # Add tool use blocks if present
+        tool_uses = [
+            block
+            for block in response.get("content", [])
+            if block.get("type") == "tool_use"
+        ]
+        if tool_uses:
+            metadata["tool_uses"] = tool_uses
+
+        return NormalizedResponseModel(
+            status="success",
+            data=text,
+            raw_response=response,
+            metadata=metadata,
+        )