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

krons/session/session.py

@@ -10,50 +10,27 @@ Branch is a named message progression with capability/resource access control.
 from __future__ import annotations
 
 import contextlib
-from collections.abc import Iterable
-from typing import TYPE_CHECKING, Any, Literal
+from collections.abc import AsyncGenerator, Iterable
+from typing import Any, Literal
 from uuid import UUID
 
-from pydantic import Field
+from pydantic import Field, model_validator
 
-from krons.core import Element, Flow, Progression
-from krons.errors import AccessError, NotFoundError
-from krons.operations.node import Operation
-from krons.operations.registry import OperationRegistry
-from krons.services import ServiceRegistry
-from krons.types import HashableModel, Unset, UnsetType, not_sentinel
+from krons.core import Element, Flow, Pile, Progression
+from krons.core.types import HashableModel, Unset, UnsetType, not_sentinel
+from krons.errors import NotFoundError
+from krons.resource import Calling, ResourceRegistry, iModel
+from krons.work.operations import Operation, OperationRegistry, RequestContext
 
 from .message import Message
 
-if TYPE_CHECKING:
-    from krons.services.backend import Calling
-
 __all__ = (
     "Branch",
     "Session",
     "SessionConfig",
-    "capabilities_must_be_subset_of_branch",
-    "resource_must_be_accessible_by_branch",
-    "resource_must_exist_in_session",
 )
 
 
-class SessionConfig(HashableModel):
-    """Session initialization configuration.
-
-    Attributes:
-        default_branch_name: Name for auto-created default branch.
-        default_capabilities: Capabilities granted to default branch.
-        default_resources: Resources accessible by default branch.
-        auto_create_default_branch: Create "main" branch on init.
-    """
-
-    default_branch_name: str | None = None
-    default_capabilities: set[str] = Field(default_factory=set)
-    default_resources: set[str] = Field(default_factory=set)
-    auto_create_default_branch: bool = True
-
-
 class Branch(Progression):
     """Message progression with capability and resource access control.
 
@@ -67,95 +44,85 @@ class Branch(Progression):
     """
 
     session_id: UUID = Field(..., frozen=True)
-    capabilities: set[str] = Field(default_factory=set)
-    resources: set[str] = Field(default_factory=set)
+    capabilities: set[str] = Field(default_factory=set, frozen=True)
+    resources: set[str] = Field(default_factory=set, frozen=True)
 
     def __repr__(self) -> str:
         name_str = f" name='{self.name}'" if self.name else ""
         return f"Branch(messages={len(self)}, session={str(self.session_id)[:8]}{name_str})"
 
 
-class Session(Element):
-    """Central orchestrator: messages, branches, services, operations.
-
-    Lifecycle:
-        1. Create session (auto-creates default branch unless disabled)
-        2. Register services and operations
-        3. Create branches for different contexts/users
-        4. Add messages, conduct operations, make service requests
+class SessionConfig(HashableModel):
+    default_branch_name: str | None = None
+    shared_capabilities: set[str] = Field(default_factory=set)
+    shared_resources: set[str] = Field(default_factory=set)
+    default_gen_model: str | None = None
+    default_parse_model: str | None = None
+    auto_create_default_branch: bool = True
 
-    Attributes:
-        user: Optional user identifier.
-        communications: Flow containing messages and branches.
-        services: Service registry for backend access.
-        operations: Operation factory registry.
-        config: Session configuration.
-        default_branch_id: Branch used when none specified.
-
-    Example:
-        session = Session(user="agent-1")
-        session.services.register("openai", openai_service)
-        session.operations.register("chat", chat_factory)
-        result = await session.conduct("chat", params={"prompt": "hello"})
-    """
 
+class Session(Element):
     user: str | None = None
-    communications: Flow[Message, Branch] = None  # type: ignore
-    services: ServiceRegistry = None  # type: ignore
-    operations: OperationRegistry = None  # type: ignore
-    config: SessionConfig = None  # type: ignore
+    communications: Flow[Message, Branch] = Field(
+        default_factory=lambda: Flow(item_type=Message)
+    )
+    resources: ResourceRegistry = Field(default_factory=ResourceRegistry)
+    operations: OperationRegistry = Field(default_factory=OperationRegistry)
+    config: SessionConfig = Field(default_factory=SessionConfig)
     default_branch_id: UUID | None = None
 
-    def __init__(
-        self,
-        user: str | None = None,
-        communications: Flow[Message, Branch] | None = None,
-        services: ServiceRegistry | None = None,
-        operations: OperationRegistry | None = None,
-        config: SessionConfig | dict | None = None,
-        default_branch_id: UUID | None = None,
-        **data,
-    ):
-        """Initialize session with optional pre-configured components.
+    @model_validator(mode="after")
+    def _validate_default_branch(self) -> Session:
+        """Auto-create default branch and register built-in operations."""
+        if self.config.auto_create_default_branch and self.default_branch is None:
+            default_branch_name = self.config.default_branch_name or "main"
+            self.create_branch(
+                name=default_branch_name,
+                capabilities=self.config.shared_capabilities,
+                resources=self.config.shared_resources,
+            )
+            self.set_default_branch(default_branch_name)
+
+        # Register built-in operations (lazy import avoids circular)
+        from krons.agent.operations import (
+            generate,
+            operate,
+            react,
+            react_stream,
+            structure,
+        )
 
-        Args:
-            user: User identifier.
-            communications: Pre-existing Flow (creates new if None).
-            services: Pre-existing ServiceRegistry (creates new if None).
-            operations: Pre-existing OperationRegistry (creates new if None).
-            config: SessionConfig or dict (uses defaults if None).
-            default_branch_id: Pre-set default branch.
-            **data: Additional Element fields.
-        """
-        super().__init__(**data)
-        self.user = user
-        self.communications = communications or Flow(item_type=Message)
-        self.services = services or ServiceRegistry()
-        self.operations = operations or OperationRegistry()
-        self.default_branch_id = default_branch_id
-
-        if config is None:
-            self.config = SessionConfig()
-        elif isinstance(config, dict):
-            self.config = SessionConfig(**config)
-        else:
-            self.config = config
+        for name, handler in (
+            ("generate", generate),
+            ("structure", structure),
+            ("operate", operate),
+            ("react", react),
+            ("react_stream", react_stream),
+        ):
+            if not self.operations.has(name):
+                self.operations.register(name, handler)
 
-        if self.config.auto_create_default_branch and self.default_branch_id is None:
-            branch = self.create_branch(
-                name=self.config.default_branch_name or "main",
-                capabilities=self.config.default_capabilities,
-                resources=self.config.default_resources,
-            )
-            self.default_branch_id = branch.id
+        return self
+
+    @property
+    def default_gen_model(self) -> iModel | None:
+        if self.config.default_gen_model is None:
+            return None
+        return self.resources.get(self.config.default_gen_model)
+
+    @property
+    def default_parse_model(self) -> iModel | None:
+        if self.config.default_parse_model is None:
+            return None
+        return self.resources.get(self.config.default_parse_model)
 
     @property
-    def messages(self):
+    def messages(self) -> Pile[Message]:
         """All messages in session (Pile[Message])."""
         return self.communications.items
 
     @property
-    def branches(self):
+    def branches(self) -> Pile[Branch]:
         """All branches in session (Pile[Branch])."""
         return self.communications.progressions
 
@@ -187,10 +154,14 @@ class Session(Element):
         Returns:
             Created Branch added to session.
         """
+        if name:
+            from .constraints import branch_name_must_be_unique
+
+            branch_name_must_be_unique(self, name)
+
         order: list[UUID] = []
         if messages:
-            for msg in messages:
-                order.append(msg.id if isinstance(msg, Message) else msg)
+            order.extend([self._coerce_id(msg) for msg in messages])
 
         branch = Branch(
             session_id=self.id,
@@ -265,9 +236,13 @@ class Session(Element):
             name=name or f"{source.name}_fork",
             messages=source.order,
             capabilities=(
-                {*source.capabilities} if capabilities is True else (capabilities or set())
+                {*source.capabilities}
+                if capabilities is True
+                else (capabilities or set())
+            ),
+            resources=(
+                {*source.resources} if resources is True else (resources or set())
             ),
-            resources=({*source.resources} if resources is True else (resources or set())),
         )
 
         forked.metadata["forked_from"] = {
@@ -288,38 +263,25 @@ class Session(Element):
 
     async def request(
         self,
-        service_name: str,
-        *,
+        name: str,
+        /,
         branch: Branch | UUID | str | None = None,
         poll_timeout: float | None = None,
         poll_interval: float | None = None,
-        **kwargs,
+        **options,
     ) -> Calling:
-        """Direct service invocation with optional access control.
-
-        Args:
-            service_name: Registered service name.
-            branch: If provided, checks service in branch.resources.
-            poll_timeout: Max wait seconds.
-            poll_interval: Poll interval seconds.
-            **kwargs: Service-specific arguments.
-
-        Returns:
-            Calling with execution results.
-
-        Raises:
-            AccessError: If branch lacks access to service.
-            NotFoundError: If service not registered.
-        """
         if branch is not None:
             resolved_branch = self.get_branch(branch)
-            resource_must_be_accessible_by_branch(resolved_branch, service_name)
 
-        service = self.services.get(service_name)
-        return await service.invoke(
+            from .constraints import resource_must_be_accessible
+
+            resource_must_be_accessible(resolved_branch, name)
+
+        resource = self.resources.get(name)
+        return await resource.invoke(
             poll_timeout=poll_timeout,
             poll_interval=poll_interval,
-            **kwargs,
+            **options,
         )
 
     async def conduct(
@@ -327,6 +289,7 @@ class Session(Element):
         operation_type: str,
         branch: Branch | UUID | str | None = None,
         params: Any | None = None,
+        verbose: bool = False,
     ) -> Operation:
         """Execute operation via registry.
 
@@ -334,6 +297,7 @@ class Session(Element):
             operation_type: Registry key.
             branch: Target branch (default if None).
             params: Operation parameters.
+            verbose: Print real-time status updates.
 
         Returns:
             Invoked Operation (result in op.execution.response).
@@ -343,16 +307,85 @@ class Session(Element):
             KeyError: Operation not registered.
         """
         resolved = self._resolve_branch(branch)
+
+        if verbose:
+            from krons.utils.display import Timer, status
+
+            branch_name = resolved.name or str(resolved.id)[:8]
+            status(
+                f"conduct({operation_type}) on branch={branch_name}",
+                style="info",
+            )
+
         op = Operation(
             operation_type=operation_type,
             parameters=params,
-            timeout=None,
-            streaming=False,
         )
+        op._verbose = verbose
         op.bind(self, resolved)
-        await op.invoke()
+
+        if verbose:
+            with Timer(f"{operation_type} completed"):
+                await op.invoke()
+
+            resp = op.execution.response
+            if op.execution.error:
+                status(f"ERROR: {op.execution.error}", style="error")
+            elif isinstance(resp, str):
+                status(f"response: {len(resp)} chars", style="success")
+            else:
+                status(f"response: {type(resp).__name__}", style="success")
+        else:
+            await op.invoke()
+
         return op
 
+    async def stream_conduct(
+        self,
+        operation_type: str,
+        branch: Branch | UUID | str | None = None,
+        params: Any | None = None,
+        verbose: bool = False,
+    ) -> AsyncGenerator[Any, None]:
+        """Stream operation results via async generator.
+
+        For streaming handlers like react_stream that yield intermediate
+        results per round. Bypasses the Operation wrapper since streaming
+        handlers produce multiple values, not a single response.
+
+        Args:
+            operation_type: Registry key (e.g. "react_stream").
+            branch: Target branch (default if None).
+            params: Operation parameters.
+            verbose: Enable real-time streaming output.
+
+        Yields:
+            Handler results (e.g., ReActAnalysis per round).
+        """
+        resolved = self._resolve_branch(branch)
+        handler = self.operations.get(operation_type)
+
+        ctx = RequestContext(
+            name=operation_type,
+            session_id=self.id,
+            branch=resolved.name or str(resolved.id),
+            _bound_session=self,
+            _bound_branch=resolved,
+            _verbose=verbose,
+        )
+
+        if verbose:
+            from krons.utils.display import status
+
+            branch_name = resolved.name or str(resolved.id)[:8]
+            status(
+                f"stream_conduct({operation_type}) on branch={branch_name}",
+                style="info",
+            )
+
+        async for result in handler(params, ctx):
+            yield result
+
     def _resolve_branch(self, branch: Branch | UUID | str | None) -> Branch:
         """Resolve to Branch, falling back to default. Raises if neither available."""
         if branch is not None:
@@ -365,47 +398,5 @@ class Session(Element):
         return (
             f"Session(messages={len(self.messages)}, "
             f"branches={len(self.branches)}, "
-            f"services={len(self.services)})"
-        )
-
-
-def resource_must_exist_in_session(session: Session, name: str) -> None:
-    """Validate service exists. Raise NotFoundError with available names if not."""
-    if not session.services.has(name):
-        raise NotFoundError(
-            f"Service '{name}' not found in session services",
-            details={"available": session.services.list_names()},
-        )
-
-
-def resource_must_be_accessible_by_branch(branch: Branch, name: str) -> None:
-    """Validate branch has resource access. Raise AccessError if not."""
-    if name not in branch.resources:
-        raise AccessError(
-            f"Branch '{branch.name}' has no access to resource '{name}'",
-            details={
-                "branch": branch.name,
-                "resource": name,
-                "available": list(branch.resources),
-            },
+            f"services={len(self.resources)})"
         )
-
-
-def capabilities_must_be_subset_of_branch(branch: Branch, capabilities: set[str]) -> None:
-    """Validate branch has all capabilities. Raise AccessError listing missing."""
-    if not capabilities.issubset(branch.capabilities):
-        missing = capabilities - branch.capabilities
-        raise AccessError(
-            f"Branch '{branch.name}' missing capabilities: {missing}",
-            details={
-                "requested": sorted(capabilities),
-                "available": sorted(branch.capabilities),
-            },
-        )
-
-
-def resolve_branch_exists_in_session(session: Session, branch: Branch | str) -> Branch:
-    """Get branch from session. Raise NotFoundError if not found."""
-    if (b_ := session.get_branch(branch, None)) is None:
-        raise NotFoundError(f"Branch '{branch}' does not exist in session")
-    return b_

krons/utils/__init__.py

@@ -38,3 +38,48 @@ from .sql._sql_validation import (
     sanitize_order_by,
     validate_identifier,
 )
+
+__all__ = (
+    # _hash
+    "GENESIS_HASH",
+    "MAX_HASH_INPUT_BYTES",
+    "HashAlgorithm",
+    "compute_chain_hash",
+    "compute_hash",
+    "hash_obj",
+    # _json_dump
+    "json_dump",
+    "json_dumpb",
+    "json_lines_iter",
+    # _to_list, _to_num
+    "to_list",
+    "to_num",
+    # _utils
+    "async_synchronized",
+    "coerce_created_at",
+    "create_path",
+    "extract_types",
+    "get_bins",
+    "import_module",
+    "is_import_installed",
+    "load_type_from_string",
+    "now_utc",
+    "register_type_prefix",
+    "synchronized",
+    "to_uuid",
+    # concurrency
+    "alcall",
+    "is_coro_func",
+    # fuzzy
+    "SimilarityAlgo",
+    "extract_json",
+    "fuzzy_json",
+    "fuzzy_match_keys",
+    "string_similarity",
+    "to_dict",
+    # sql
+    "MAX_IDENTIFIER_LENGTH",
+    "SAFE_IDENTIFIER_PATTERN",
+    "sanitize_order_by",
+    "validate_identifier",
+)

krons/utils/_function_arg_parser.py

@@ -0,0 +1,99 @@
+import types
+from typing import Any, Union, get_args, get_origin
+
+from pydantic import BaseModel
+
+
+def map_positional_args(
+    arguments: dict[str, Any], param_names: list[str]
+) -> dict[str, Any]:
+    """Map positional arguments (_pos_0, _pos_1, ...) to actual parameter names."""
+    mapped = {}
+    pos_count = 0
+
+    for key, value in arguments.items():
+        if key.startswith("_pos_"):
+            if pos_count >= len(param_names):
+                raise ValueError(
+                    f"Too many positional arguments (expected {len(param_names)})"
+                )
+            mapped[param_names[pos_count]] = value
+            pos_count += 1
+        else:
+            # Keep keyword arguments as-is
+            mapped[key] = value
+
+    return mapped
+
+
+def _get_nested_fields_from_annotation(annotation) -> set[str]:
+    """Extract all field names from an annotation that may be a Pydantic model or Union."""
+    origin = get_origin(annotation)
+
+    # Handle Union types (typing.Union or types.UnionType)
+    if origin is Union or isinstance(annotation, types.UnionType):
+        union_members = get_args(annotation)
+        all_fields = set()
+        for member in union_members:
+            if member is type(None):
+                continue
+            # Recursively check nested unions or models
+            nested = _get_nested_fields_from_annotation(member)
+            all_fields.update(nested)
+        return all_fields
+
+    # Handle direct Pydantic model
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return set(annotation.model_fields.keys())
+
+    # Handle Pydantic model class (not instance)
+    if hasattr(annotation, "model_fields"):
+        return set(annotation.model_fields.keys())
+
+    return set()
+
+
+def nest_arguments_by_schema(arguments: dict[str, Any], schema_cls) -> dict[str, Any]:
+    """Restructure flat arguments into nested format based on schema structure."""
+    if not schema_cls or not hasattr(schema_cls, "model_fields"):
+        return arguments
+
+    # Get top-level field names
+    top_level_fields = set(schema_cls.model_fields.keys())
+
+    # Find fields that are nested objects (Pydantic models or unions)
+    nested_field_mappings = {}
+    for field_name, field_info in schema_cls.model_fields.items():
+        annotation = field_info.annotation
+        nested_fields = _get_nested_fields_from_annotation(annotation)
+        if nested_fields:
+            nested_field_mappings[field_name] = nested_fields
+
+    # If no nested fields detected, return as-is
+    if not nested_field_mappings:
+        return arguments
+
+    # Separate top-level args from nested args
+    result: dict[str, Any] = {}
+    nested_args: dict[str, dict[str, Any]] = {}
+
+    for key, value in arguments.items():
+        if key in top_level_fields:
+            # This is a top-level field
+            result[key] = value
+        else:
+            # Check if this belongs to a nested field
+            for nested_field, nested_keys in nested_field_mappings.items():
+                if key in nested_keys:
+                    if nested_field not in nested_args:
+                        nested_args[nested_field] = {}
+                    nested_args[nested_field][key] = value
+                    break
+            else:
+                # Unknown field - keep at top level (will fail validation later)
+                result[key] = value
+
+    # Add nested structures to result
+    result.update(nested_args)
+
+    return result