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

krons/agent/third_party/openai_models.py

@@ -0,0 +1,295 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import warnings
+from enum import Enum
+from typing import Any, Literal, Union
+
+from pydantic import BaseModel, Field
+
+warnings.filterwarnings("ignore", category=UserWarning, module="pydantic")
+
+
+# ---------- Roles & content parts ----------
+
+
+class ChatRole(str, Enum):
+    system = "system"
+    developer = "developer"  # modern system-like role
+    user = "user"
+    assistant = "assistant"
+    tool = "tool"  # for tool results sent back to the model
+
+
+class TextPart(BaseModel):
+    """Text content part for multimodal messages."""
+
+    type: Literal["text"] = "text"
+    text: str
+
+
+class ImageURLObject(BaseModel):
+    """Image URL object; 'detail' is optional and model-dependent."""
+
+    url: str
+    detail: Literal["auto", "low", "high"] | None = Field(
+        default=None,
+        description="Optional detail control for vision models (auto/low/high).",
+    )
+
+
+class ImageURLPart(BaseModel):
+    """Image content part for multimodal messages."""
+
+    type: Literal["image_url"] = "image_url"
+    image_url: ImageURLObject
+
+
+ContentPart = TextPart | ImageURLPart
+
+
+# ---------- Tool-calling structures ----------
+
+
+class FunctionDef(BaseModel):
+    """JSON Schema function definition for tool-calling."""
+
+    name: str
+    description: str | None = None
+    parameters: dict[str, Any] = Field(
+        default_factory=dict,
+        description="JSON Schema describing function parameters.",
+    )
+
+
+class FunctionTool(BaseModel):
+    type: Literal["function"] = "function"
+    function: FunctionDef
+
+
+class FunctionCall(BaseModel):
+    """Legacy function_call field on assistant messages."""
+
+    name: str
+    arguments: str
+
+
+class ToolCallFunction(BaseModel):
+    name: str
+    arguments: str
+
+
+class ToolCall(BaseModel):
+    """Assistant's tool call (modern)."""
+
+    id: str
+    type: Literal["function"] = "function"
+    function: ToolCallFunction
+
+
+class ToolChoiceFunction(BaseModel):
+    """Explicit tool selection."""
+
+    type: Literal["function"] = "function"
+    function: dict[str, str]  # {"name": "<function_name>"}
+
+
+ToolChoice = Union[Literal["auto", "none"], ToolChoiceFunction]
+
+
+# ---------- Response format (structured outputs) ----------
+
+
+class ResponseFormatText(BaseModel):
+    type: Literal["text"] = "text"
+
+
+class ResponseFormatJSONObject(BaseModel):
+    type: Literal["json_object"] = "json_object"
+
+
+class JSONSchemaFormat(BaseModel):
+    name: str
+    schema_: dict[str, Any] = Field(
+        alias="schema", description="JSON Schema definition"
+    )
+    strict: bool | None = Field(
+        default=None,
+        description="If true, disallow unspecified properties (strict schema).",
+    )
+
+    model_config = {"populate_by_name": True}
+
+
+class ResponseFormatJSONSchema(BaseModel):
+    type: Literal["json_schema"] = "json_schema"
+    json_schema: JSONSchemaFormat
+
+
+ResponseFormat = Union[
+    ResponseFormatText,
+    ResponseFormatJSONObject,
+    ResponseFormatJSONSchema,
+]
+
+
+# ---------- Messages (discriminated by role) ----------
+
+
+class SystemMessage(BaseModel):
+    role: Literal[ChatRole.system] = ChatRole.system
+    content: str | list[ContentPart]
+    name: str | None = None  # optional per API
+
+
+class DeveloperMessage(BaseModel):
+    role: Literal[ChatRole.developer] = ChatRole.developer
+    content: str | list[ContentPart]
+    name: str | None = None
+
+
+class UserMessage(BaseModel):
+    role: Literal[ChatRole.user] = ChatRole.user
+    content: str | list[ContentPart]
+    name: str | None = None
+
+
+class AssistantMessage(BaseModel):
+    role: Literal[ChatRole.assistant] = ChatRole.assistant
+    # Either textual content, or only tool_calls (when asking you to call tools)
+    content: str | list[ContentPart] | None = None
+    name: str | None = None
+    tool_calls: list[ToolCall] | None = None  # modern tool-calling result
+    function_call: FunctionCall | None = None  # legacy function-calling result
+
+
+class ToolMessage(BaseModel):
+    role: Literal[ChatRole.tool] = ChatRole.tool
+    content: str  # tool output returned to the model
+    tool_call_id: str  # must reference the assistant's tool_calls[i].id
+
+
+ChatMessage = (
+    SystemMessage | DeveloperMessage | UserMessage | AssistantMessage | ToolMessage
+)
+
+# ---------- Stream options ----------
+
+
+class StreamOptions(BaseModel):
+    include_usage: bool | None = Field(
+        default=None,
+        description="If true, a final streamed chunk includes token usage.",
+    )
+
+
+# ---------- Main request model ----------
+
+
+class OpenAIChatCompletionsRequest(BaseModel):
+    """
+    Request body for OpenAI Chat Completions.
+    Endpoint: POST https://api.openai.com/v1/chat/completions
+    """
+
+    # Required
+    model: str = Field(..., description="Model name, e.g., 'gpt-4o', 'gpt-4o-mini'.")  # type: ignore
+    messages: list[ChatMessage] = Field(
+        ...,
+        description="Conversation so far, including system/developer context.",
+    )
+
+    # Sampling & penalties
+    temperature: float | None = Field(
+        default=None, ge=0.0, le=2.0, description="Higher is more random."
+    )
+    top_p: float | None = Field(
+        default=None, ge=0.0, le=1.0, description="Nucleus sampling."
+    )
+    presence_penalty: float | None = Field(
+        default=None,
+        ge=-2.0,
+        le=2.0,
+        description="Encourages new topics; -2..2.",
+    )
+    frequency_penalty: float | None = Field(
+        default=None,
+        ge=-2.0,
+        le=2.0,
+        description="Penalizes repetition; -2..2.",
+    )
+
+    # Token limits
+    max_completion_tokens: int | None = Field(
+        default=None,
+        description="Preferred cap on generated tokens (newer models).",
+    )
+    max_tokens: int | None = Field(
+        default=None,
+        description="Legacy completion cap (still accepted by many models).",
+    )
+
+    # Count, stop, logits
+    n: int | None = Field(default=None, ge=1, description="# of choices to generate.")
+    stop: str | list[str] | None = Field(default=None, description="Stop sequence(s).")
+    logit_bias: dict[str, float] | None = Field(
+        default=None,
+        description="Map of token-id -> bias (-100..100).",
+    )
+    seed: int | None = Field(
+        default=None,
+        description="Optional reproducibility seed (model-dependent).",
+    )
+    logprobs: bool | None = None
+    top_logprobs: int | None = Field(
+        default=None,
+        ge=0,
+        description="When logprobs is true, how many top tokens to include.",
+    )
+
+    # Tool calling (modern)
+    tools: list[FunctionTool] | None = None
+    tool_choice: ToolChoice | None = Field(
+        default=None,
+        description="'auto' (default), 'none', or a function selection.",
+    )
+    parallel_tool_calls: bool | None = Field(
+        default=None,
+        description="Allow multiple tool calls in a single assistant turn.",
+    )
+
+    # Legacy function-calling (still supported)
+    functions: list[FunctionDef] | None = None
+    function_call: Literal["none", "auto"] | FunctionCall | None = None
+
+    # Structured outputs
+    response_format: ResponseFormat | None = None
+
+    # Streaming
+    stream: bool | None = None
+    stream_options: StreamOptions | None = None
+
+    # Routing / tiering
+    service_tier: Literal["auto", "default", "flex", "scale", "priority"] | None = (
+        Field(
+            default=None,
+            description="Processing tier; requires account eligibility.",
+        )
+    )
+
+    # Misc
+    user: str | None = Field(
+        default=None,
+        description="End-user identifier for abuse monitoring & analytics.",
+    )
+    store: bool | None = Field(
+        default=None,
+        description="Whether to store the response server-side (model-dependent).",
+    )
+    metadata: dict[str, Any] | None = None
+    reasoning_effort: Literal["low", "medium", "high"] | None = Field(
+        default=None,
+        description="For reasoning models: trade-off between speed and accuracy.",
+    )

krons/agent/tool.py

@@ -0,0 +1,291 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tool - Callable function backend for agents.
+
+A Tool wraps a callable function with:
+- Parameter validation via Pydantic schema
+- Normalized response format
+- Integration with the ResourceBackend/Calling pattern
+
+Usage:
+    @tool(name="calculator", description="Perform calculations")
+    async def calculator(expression: str) -> float:
+        return eval(expression)  # simplified example
+
+    # Or create manually:
+    tool = Tool(
+        config=ToolConfig(
+            provider="local",
+            name="calculator",
+            description="Perform calculations",
+        ),
+        handler=calculator,
+    )
+    response = await tool.call(arguments={"expression": "2 + 2"})
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any, get_type_hints
+
+from pydantic import BaseModel, Field
+
+from krons.resource.backend import (
+    Calling,
+    NormalizedResponseModel,
+    ResourceBackend,
+    ResourceConfig,
+)
+
+logger = logging.getLogger(__name__)
+
+__all__ = (
+    "Tool",
+    "ToolCalling",
+    "ToolConfig",
+    "tool",
+)
+
+
+class ToolConfig(ResourceConfig):
+    """Configuration for a Tool backend.
+
+    Extends ResourceConfig with tool-specific fields.
+    """
+
+    description: str = Field(default="", description="Human-readable tool description")
+    parameters_schema: type[BaseModel] | None = Field(
+        default=None,
+        exclude=True,
+        description="Pydantic model for parameter validation",
+    )
+    return_type: type | None = Field(
+        default=None,
+        exclude=True,
+        description="Expected return type (for documentation)",
+    )
+
+
+class ToolCalling(Calling):
+    """Calling event for Tool execution.
+
+    Wraps a tool invocation with the standard Calling lifecycle (hooks, etc).
+    """
+
+    arguments: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arguments to pass to the tool handler",
+    )
+
+    @property
+    def call_args(self) -> dict:
+        """Get arguments for backend.call()."""
+        return {"arguments": self.arguments}
+
+
+class Tool(ResourceBackend):
+    """Tool backend - wraps a callable function.
+
+    Attributes:
+        config: ToolConfig with name, description, schema
+        handler: The callable function to execute
+    """
+
+    config: ToolConfig = Field(..., description="Tool configuration")
+    handler: Callable[..., Any | Awaitable[Any]] = Field(
+        ...,
+        exclude=True,
+        description="The callable function to execute",
+    )
+
+    @property
+    def event_type(self) -> type[ToolCalling]:
+        """Return ToolCalling as the event type for this backend."""
+        return ToolCalling
+
+    @property
+    def description(self) -> str:
+        """Tool description from config."""
+        return self.config.description
+
+    @property
+    def parameters_schema(self) -> type[BaseModel] | None:
+        """Parameters schema from config."""
+        return self.config.parameters_schema
+
+    def _validate_arguments(self, arguments: dict[str, Any]) -> dict[str, Any]:
+        """Validate arguments against schema if defined.
+
+        Args:
+            arguments: Arguments dict to validate
+
+        Returns:
+            Validated arguments dict
+
+        Raises:
+            ValueError: If validation fails
+        """
+        if self.parameters_schema is None:
+            return arguments
+
+        try:
+            validated = self.parameters_schema.model_validate(arguments)
+            return validated.model_dump()
+        except Exception as e:
+            raise ValueError(f"Tool argument validation failed: {e}") from e
+
+    async def call(
+        self, arguments: dict[str, Any] | None = None
+    ) -> NormalizedResponseModel:
+        """Execute the tool handler with given arguments.
+
+        Args:
+            arguments: Arguments to pass to handler
+
+        Returns:
+            NormalizedResponseModel with result or error
+        """
+        arguments = arguments or {}
+
+        try:
+            # Validate arguments
+            validated_args = self._validate_arguments(arguments)
+
+            # Execute handler (sync or async)
+            if inspect.iscoroutinefunction(self.handler):
+                result = await self.handler(**validated_args)
+            else:
+                result = self.handler(**validated_args)
+
+            return self.normalize_response(result)
+
+        except Exception as e:
+            logger.exception(f"Tool '{self.name}' execution failed: {e}")
+            return NormalizedResponseModel(
+                status="error",
+                data=None,
+                error=str(e),
+                raw_response={"error": str(e), "arguments": arguments},
+            )
+
+    def normalize_response(self, raw_response: Any) -> NormalizedResponseModel:
+        """Normalize tool result to standard format.
+
+        Args:
+            raw_response: Raw result from handler
+
+        Returns:
+            NormalizedResponseModel with status and data
+        """
+        return NormalizedResponseModel(
+            status="success",
+            data=raw_response,
+            raw_response={"result": raw_response},
+        )
+
+    def to_openai_schema(self) -> dict[str, Any]:
+        """Generate OpenAI-compatible function schema.
+
+        Returns:
+            Dict with name, description, parameters schema
+        """
+        schema: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+        }
+
+        if self.parameters_schema:
+            # Get JSON schema from Pydantic model
+            json_schema = self.parameters_schema.model_json_schema()
+            # OpenAI expects parameters directly, not wrapped
+            schema["parameters"] = {
+                "type": "object",
+                "properties": json_schema.get("properties", {}),
+                "required": json_schema.get("required", []),
+            }
+        else:
+            schema["parameters"] = {"type": "object", "properties": {}}
+
+        return schema
+
+    def to_anthropic_schema(self) -> dict[str, Any]:
+        """Generate Anthropic-compatible tool schema.
+
+        Returns:
+            Dict with name, description, input_schema
+        """
+        schema: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+        }
+
+        if self.parameters_schema:
+            json_schema = self.parameters_schema.model_json_schema()
+            schema["input_schema"] = {
+                "type": "object",
+                "properties": json_schema.get("properties", {}),
+                "required": json_schema.get("required", []),
+            }
+        else:
+            schema["input_schema"] = {"type": "object", "properties": {}}
+
+        return schema
+
+
+def tool(
+    name: str | None = None,
+    description: str = "",
+    provider: str = "local",
+    parameters_schema: type[BaseModel] | None = None,
+) -> Callable[[Callable[..., Any]], Tool]:
+    """Decorator to create a Tool from a function.
+
+    Args:
+        name: Tool name (defaults to function name)
+        description: Human-readable description
+        provider: Provider name (default: "local")
+        parameters_schema: Optional Pydantic model for parameter validation
+
+    Returns:
+        Decorator that creates a Tool
+
+    Example:
+        @tool(name="greet", description="Greet a person")
+        async def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        # Use directly:
+        response = await greet.call(arguments={"name": "World"})
+    """
+
+    def decorator(func: Callable[..., Any]) -> Tool:
+        tool_name = name or func.__name__
+        tool_desc = description or func.__doc__ or ""
+
+        # Try to infer parameters schema from type hints
+        schema = parameters_schema
+        if schema is None:
+            hints = get_type_hints(func) if hasattr(func, "__annotations__") else {}
+            hints.pop("return", None)
+            if hints:
+                # Dynamically create a Pydantic model from type hints
+                schema = type(
+                    f"{tool_name.title()}Params",
+                    (BaseModel,),
+                    {"__annotations__": hints},
+                )
+
+        config = ToolConfig(
+            provider=provider,
+            name=tool_name,
+            description=tool_desc,
+            parameters_schema=schema,
+        )
+
+        return Tool(config=config, handler=func)
+
+    return decorator

krons/core/__init__.py

@@ -0,0 +1,127 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Core module - Foundation primitives and submodules.
+
+Re-exports base classes from core/base/ and exposes submodules:
+- types: Sentinels, base types, DB types
+- specs: Spec definitions, Operable, adapters
+
+Note: Session (Message, Branch, Session, Exchange) is now at krons.session
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Lazy import mapping - delegates to core.base
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # Registries
+    "NODE_REGISTRY": ("krons.core.base", "NODE_REGISTRY"),
+    "PERSISTABLE_NODE_REGISTRY": ("krons.core.base", "PERSISTABLE_NODE_REGISTRY"),
+    # Classes
+    "Broadcaster": ("krons.core.base", "Broadcaster"),
+    "Edge": ("krons.core.base", "Edge"),
+    "EdgeCondition": ("krons.core.base", "EdgeCondition"),
+    "Element": ("krons.core.base", "Element"),
+    "Event": ("krons.core.base", "Event"),
+    "EventBus": ("krons.core.base", "EventBus"),
+    "EventStatus": ("krons.core.base", "EventStatus"),
+    "Execution": ("krons.core.base", "Execution"),
+    "Executor": ("krons.core.base", "Executor"),
+    "Flow": ("krons.core.base", "Flow"),
+    "Graph": ("krons.core.base", "Graph"),
+    "Handler": ("krons.core.base", "Handler"),
+    "Node": ("krons.core.base", "Node"),
+    "NodeConfig": ("krons.core.base", "NodeConfig"),
+    "Pile": ("krons.core.base", "Pile"),
+    "Processor": ("krons.core.base", "Processor"),
+    "Progression": ("krons.core.base", "Progression"),
+    # Functions
+    "create_node": ("krons.core.base", "create_node"),
+    "generate_all_ddl": ("krons.core.base", "generate_all_ddl"),
+    "generate_ddl": ("krons.core.base", "generate_ddl"),
+    "get_fk_dependencies": ("krons.core.base", "get_fk_dependencies"),
+}
+
+_LOADED: dict[str, object] = {}
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import attributes on first access."""
+    if name in _LOADED:
+        return _LOADED[name]
+
+    if name in _LAZY_IMPORTS:
+        from importlib import import_module
+
+        module_name, attr_name = _LAZY_IMPORTS[name]
+        module = import_module(module_name)
+        value = getattr(module, attr_name)
+        _LOADED[name] = value
+        return value
+
+    raise AttributeError(f"module 'krons.core' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Return all available attributes for autocomplete."""
+    return list(__all__)
+
+
+# TYPE_CHECKING block for static analysis
+if TYPE_CHECKING:
+    from krons.core.base import (
+        NODE_REGISTRY,
+        PERSISTABLE_NODE_REGISTRY,
+        Broadcaster,
+        Edge,
+        EdgeCondition,
+        Element,
+        Event,
+        EventBus,
+        EventStatus,
+        Execution,
+        Executor,
+        Flow,
+        Graph,
+        Handler,
+        Node,
+        NodeConfig,
+        Pile,
+        Processor,
+        Progression,
+        create_node,
+        generate_all_ddl,
+        generate_ddl,
+        get_fk_dependencies,
+    )
+
+__all__ = [
+    # constants/registries
+    "NODE_REGISTRY",
+    "PERSISTABLE_NODE_REGISTRY",
+    # classes
+    "Broadcaster",
+    "Edge",
+    "EdgeCondition",
+    "Element",
+    "Event",
+    "EventBus",
+    "EventStatus",
+    "Execution",
+    "Executor",
+    "Flow",
+    "Graph",
+    "Handler",
+    "Node",
+    "NodeConfig",
+    "Pile",
+    "Processor",
+    "Progression",
+    # functions
+    "create_node",
+    "generate_all_ddl",
+    "generate_ddl",
+    "get_fk_dependencies",
+]