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

{kronos → krons}/session/__init__.py

@@ -10,23 +10,19 @@ Core types:
     Exchange: Async message router between entity mailboxes.
 
 Validators (raise on failure):
-    resource_must_exist_in_session
-    resource_must_be_accessible_by_branch
-    capabilities_must_be_subset_of_branch
-    resolve_branch_exists_in_session
+    resource_must_exist
+    resource_must_be_accessible
+    capabilities_must_be_granted
 """
 
+from .constraints import (
+    capabilities_must_be_granted,
+    resource_must_be_accessible,
+    resource_must_exist,
+)
 from .exchange import Exchange
 from .message import Message
-from .session import (
-    Branch,
-    Session,
-    SessionConfig,
-    capabilities_must_be_subset_of_branch,
-    resolve_branch_exists_in_session,
-    resource_must_be_accessible_by_branch,
-    resource_must_exist_in_session,
-)
+from .session import Branch, Session, SessionConfig
 
 __all__ = (
     "Branch",
@@ -34,8 +30,7 @@ __all__ = (
     "Message",
     "Session",
     "SessionConfig",
-    "capabilities_must_be_subset_of_branch",
-    "resolve_branch_exists_in_session",
-    "resource_must_be_accessible_by_branch",
-    "resource_must_exist_in_session",
+    "capabilities_must_be_granted",
+    "resource_must_be_accessible",
+    "resource_must_exist",
 )

krons/session/constraints.py

@@ -0,0 +1,70 @@
+from krons.errors import AccessError, ConfigurationError, ExistsError, NotFoundError
+
+__all__ = (
+    "resource_must_exist",
+    "resource_must_be_accessible",
+    "capabilities_must_be_granted",
+    "branch_name_must_be_unique",
+    "genai_model_must_be_configured",
+)
+
+
+def resource_must_exist(session, name: str):
+    """Validate resource exists in session. Raise NotFoundError if not."""
+    if not session.resources.has(name):
+        raise NotFoundError(
+            f"Service '{name}' not found in session services",
+            details={"available": session.resources.list_names()},
+        )
+
+
+def resource_must_be_accessible(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),
+            },
+        )
+
+
+def capabilities_must_be_granted(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 branch_name_must_be_unique(session, name: str) -> None:
+    try:
+        session.communications.get_progression(name)
+        # If we get here, the name exists - not unique
+        raise ExistsError(f"Branch with name '{name}' already exists")
+    except KeyError:
+        # KeyError means name not found - it's unique, which is good
+        pass
+
+
+def genai_model_must_be_configured(session) -> None:
+    """Validate session has a default GenAI model configured.
+
+    Args:
+        session: Session to check
+
+    Raises:
+        ConfigurationError: If no default model configured
+    """
+    if session.default_gen_model is None:
+        raise ConfigurationError(
+            "Session has no default_gen_model configured",
+            details={"session_id": str(session.id)},
+        )

{kronos → krons}/session/exchange.py

@@ -14,9 +14,9 @@ from uuid import UUID
 
 from pydantic import PrivateAttr
 
-from kronos.core import Element, Flow, Pile, Progression
-from kronos.errors import ExistsError
-from kronos.utils import concurrency
+from krons.core import Element, Flow, Pile, Progression
+from krons.errors import ExistsError
+from krons.utils import concurrency
 
 from .message import Message
 
@@ -134,11 +134,17 @@ class Exchange(Element):
                             except Exception:
                                 message_copy = message.model_copy()
                             deliveries.append((other_id, message_copy))
-                elif message.recipient is not None and message.recipient in self._owner_index:
+                elif (
+                    message.recipient is not None
+                    and message.recipient in self._owner_index
+                ):
                     deliveries.append((message.recipient, message))
         if deliveries:
             await concurrency.gather(
-                *[self._deliver_to(recipient_id, message) for recipient_id, message in deliveries],
+                *[
+                    self._deliver_to(recipient_id, message)
+                    for recipient_id, message in deliveries
+                ],
                 return_exceptions=True,
             )
 
@@ -196,7 +202,9 @@ class Exchange(Element):
         if flow is None:
             raise ValueError(f"Sender {sender} not registered")
 
-        message = Message(sender=sender, recipient=recipient, content=content, channel=channel)
+        message = Message(
+            sender=sender, recipient=recipient, content=content, channel=channel
+        )
         flow.add_item(message, progressions=OUTBOX)
         return message
 

{kronos → krons}/session/message.py

@@ -8,7 +8,7 @@ from uuid import UUID
 
 from pydantic import Field, field_validator
 
-from kronos.core import Node
+from krons.core import Node
 
 
 class Message(Node):
@@ -27,7 +27,9 @@ class Message(Node):
     content: Any
     sender: UUID | None = None
     recipient: UUID | None = None
-    channel: str | None = Field(None, description="Optional namespace for message grouping")
+    channel: str | None = Field(
+        None, description="Optional namespace for message grouping"
+    )
 
     @property
     def is_broadcast(self) -> bool:

krons/session/registry.py

@@ -0,0 +1,35 @@
+from krons.core import Pile
+from krons.core.types import ID
+
+from .session import Session
+
+SESSION_REGISTRY: Pile[Session] = Pile(item_type=Session, strict_type=True)
+
+
+async def get_session(session_id: ID[Session]) -> Session:
+    if session_id not in SESSION_REGISTRY:
+        raise ValueError(f"Session with id {session_id} not found in registry.")
+    async with SESSION_REGISTRY:
+        return SESSION_REGISTRY[session_id]
+
+
+async def create_session():
+    session = Session()
+    async with SESSION_REGISTRY:
+        SESSION_REGISTRY.add(session)
+
+
+async def delete_session(session_id: ID[Session]):
+    if session_id not in SESSION_REGISTRY:
+        raise ValueError(f"Session with id {session_id} not found in registry.")
+    async with SESSION_REGISTRY:
+        SESSION_REGISTRY.remove(session_id)
+
+
+async def list_sessions_ids() -> list[ID[Session]]:
+    return list(SESSION_REGISTRY.keys())
+
+
+async def clear_sessions():
+    async with SESSION_REGISTRY:
+        SESSION_REGISTRY.clear()

{kronos → 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 kronos.core import Element, Flow, Progression
-from kronos.errors import AccessError, NotFoundError
-from kronos.operations.node import Operation
-from kronos.operations.registry import OperationRegistry
-from kronos.services import ServiceRegistry
-from kronos.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 kronos.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_