krons 0.2.0__tar.gz → 0.2.2__tar.gz

{krons-0.2.0 → krons-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: krons
-Version: 0.2.0
+Version: 0.2.2
 Summary: Spec-based composable framework for building type-safe systems
 Project-URL: Homepage, https://github.com/khive-ai/krons
 Project-URL: Repository, https://github.com/khive-ai/krons

{krons-0.2.0 → krons-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "krons"
-version = "0.2.0"
+version = "0.2.2"
 description = "Spec-based composable framework for building type-safe systems"
 readme = "README.md"
 requires-python = ">=3.11"

{krons-0.2.0 → krons-0.2.2}/src/krons/core/__init__.py

@@ -21,6 +21,7 @@ _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
     "PERSISTABLE_NODE_REGISTRY": ("krons.core.base", "PERSISTABLE_NODE_REGISTRY"),
     # Classes
     "Broadcaster": ("krons.core.base", "Broadcaster"),
+    "DataLoggerConfig": ("krons.core.base", "DataLoggerConfig"),
     "Edge": ("krons.core.base", "Edge"),
     "EdgeCondition": ("krons.core.base", "EdgeCondition"),
     "Element": ("krons.core.base", "Element"),
@@ -75,6 +76,7 @@ if TYPE_CHECKING:
         NODE_REGISTRY,
         PERSISTABLE_NODE_REGISTRY,
         Broadcaster,
+        DataLoggerConfig,
         Edge,
         EdgeCondition,
         Element,
@@ -103,6 +105,7 @@ __all__ = [
     "PERSISTABLE_NODE_REGISTRY",
     # classes
     "Broadcaster",
+    "DataLoggerConfig",
     "Edge",
     "EdgeCondition",
     "Element",

{krons-0.2.0 → krons-0.2.2}/src/krons/core/base/__init__.py

@@ -26,6 +26,8 @@ _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
     "Edge": ("krons.core.base.graph", "Edge"),
     "EdgeCondition": ("krons.core.base.graph", "EdgeCondition"),
     "Graph": ("krons.core.base.graph", "Graph"),
+    # log
+    "DataLoggerConfig": ("krons.core.base.log", "DataLoggerConfig"),
     # node
     "NODE_REGISTRY": ("krons.core.base.node", "NODE_REGISTRY"),
     "PERSISTABLE_NODE_REGISTRY": ("krons.core.base.node", "PERSISTABLE_NODE_REGISTRY"),
@@ -77,6 +79,7 @@ if TYPE_CHECKING:
     from .eventbus import EventBus, Handler
     from .flow import Flow
     from .graph import Edge, EdgeCondition, Graph
+    from .log import DataLoggerConfig
     from .node import (
         NODE_REGISTRY,
         PERSISTABLE_NODE_REGISTRY,
@@ -97,6 +100,7 @@ __all__ = [
     "PERSISTABLE_NODE_REGISTRY",
     # classes
     "Broadcaster",
+    "DataLoggerConfig",
     "Edge",
     "EdgeCondition",
     "Element",

krons-0.2.2/src/krons/core/base/log.py

@@ -0,0 +1,32 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Logging configuration for Session message persistence.
+
+Provides DataLoggerConfig for configuring automatic message dumps.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field
+
+from krons.core.types import HashableModel
+
+__all__ = ("DataLoggerConfig",)
+
+
+class DataLoggerConfig(HashableModel):
+    """Configuration for Session message persistence.
+
+    Attributes:
+        persist_dir: Directory for dump files.
+        extension: Output format (.json array or .jsonl newline-delimited).
+        auto_save_on_exit: Register atexit handler on Session creation.
+    """
+
+    persist_dir: str | Path = Field(default="./logs")
+    extension: Literal[".json", ".jsonl"] = Field(default=".jsonl")
+    auto_save_on_exit: bool = Field(default=True)

{krons-0.2.0 → krons-0.2.2}/src/krons/session/session.py

@@ -9,12 +9,16 @@ Branch is a named message progression with capability/resource access control.
 
 from __future__ import annotations
 
+import atexit
 import contextlib
 from collections.abc import AsyncGenerator, Iterable
+from pathlib import Path
 from typing import Any, Literal
+
+from krons.core.base.log import DataLoggerConfig
 from uuid import UUID
 
-from pydantic import Field, model_validator
+from pydantic import Field, PrivateAttr, model_validator
 
 from krons.core import Element, Flow, Pile, Progression
 from krons.core.types import HashableModel, Unset, UnsetType, not_sentinel
@@ -59,6 +63,10 @@ class SessionConfig(HashableModel):
     default_gen_model: str | None = None
     default_parse_model: str | None = None
     auto_create_default_branch: bool = True
+    log_config: DataLoggerConfig | None = Field(
+        default=None,
+        description="DataLoggerConfig for auto-logging (None = disabled)",
+    )
 
 
 class Session(Element):
@@ -71,6 +79,9 @@ class Session(Element):
     config: SessionConfig = Field(default_factory=SessionConfig)
     default_branch_id: UUID | None = None
 
+    _registered_atexit: bool = PrivateAttr(default=False)
+    _dump_count: int = PrivateAttr(default=0)
+
     @model_validator(mode="after")
     def _validate_default_branch(self) -> Session:
         """Auto-create default branch and register built-in operations."""
@@ -83,6 +94,15 @@ class Session(Element):
             )
             self.set_default_branch(default_branch_name)
 
+        # Register atexit handler if configured
+        if (
+            self.config.log_config is not None
+            and self.config.log_config.auto_save_on_exit
+            and not self._registered_atexit
+        ):
+            atexit.register(self._save_at_exit)
+            self._registered_atexit = True
+
         # Register built-in operations (lazy import avoids circular)
         from krons.agent.operations import (
             generate,
@@ -386,6 +406,99 @@ class Session(Element):
         async for result in handler(params, ctx):
             yield result
 
+    def dump_messages(self, clear: bool = False) -> Path | None:
+        """Sync dump all session messages to file.
+
+        Args:
+            clear: Clear messages after dump (default False).
+
+        Returns:
+            Path to written file, or None if no log_config or no messages.
+        """
+        from krons.utils import create_path, json_dumpb, json_lines_iter
+        from krons.utils.concurrency import run_async
+
+        if self.config.log_config is None or len(self.messages) == 0:
+            return None
+
+        cfg = self.config.log_config
+        self._dump_count += 1
+
+        filepath = run_async(
+            create_path(
+                directory=cfg.persist_dir,
+                filename=f"session_{str(self.id)[:8]}_{self._dump_count}",
+                extension=cfg.extension,
+                timestamp=True,
+                file_exist_ok=True,
+            )
+        )
+
+        items = [msg.to_dict(mode="json") for msg in self.messages]
+
+        std_path = Path(filepath)
+        if cfg.extension == ".jsonl":
+            with std_path.open("wb") as f:
+                for chunk in json_lines_iter(items, safe_fallback=True):
+                    f.write(chunk)
+        else:
+            data = json_dumpb(items, safe_fallback=True)
+            std_path.write_bytes(data)
+
+        if clear:
+            self.communications.items.clear()
+
+        return std_path
+
+    async def adump_messages(self, clear: bool = False) -> Path | None:
+        """Async dump all session messages to file with lock protection.
+
+        Args:
+            clear: Clear messages after dump (default False).
+
+        Returns:
+            Path to written file, or None if no log_config or no messages.
+        """
+        from krons.utils import create_path, json_dumpb, json_lines_iter
+
+        if self.config.log_config is None or len(self.messages) == 0:
+            return None
+
+        cfg = self.config.log_config
+
+        async with self.messages:
+            self._dump_count += 1
+
+            filepath = await create_path(
+                directory=cfg.persist_dir,
+                filename=f"session_{str(self.id)[:8]}_{self._dump_count}",
+                extension=cfg.extension,
+                timestamp=True,
+                file_exist_ok=True,
+            )
+
+            items = [msg.to_dict(mode="json") for msg in self.messages]
+
+            if cfg.extension == ".jsonl":
+                content = b"".join(json_lines_iter(items, safe_fallback=True))
+                await filepath.write_bytes(content)
+            else:
+                data = json_dumpb(items, safe_fallback=True)
+                await filepath.write_bytes(data)
+
+            if clear:
+                self.communications.items.clear()
+
+        return Path(filepath)
+
+    def _save_at_exit(self) -> None:
+        """atexit callback. Dumps messages synchronously. Errors are suppressed."""
+        if len(self.messages) > 0:
+            try:
+                self.dump_messages(clear=False)
+            except Exception:
+                pass  # Silent failure during interpreter shutdown
+
     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:

{krons-0.2.0 → krons-0.2.2}/src/krons/work/__init__.py

@@ -32,7 +32,6 @@ Two complementary patterns at different abstraction levels:
             return await self.llm.chat(**kwargs)
 
 Core concepts:
-- Phrase: Typed operation signature (inputs -> outputs)
 - Form: Data binding + scheduling (stateful artifact)
 - Report: Multi-step workflow declaration (stateful artifact)
 - Worker: Execution capability (stateless station)
@@ -53,11 +52,6 @@ _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
     "ParsedAssignment": ("krons.work.form", "ParsedAssignment"),
     "parse_assignment": ("krons.work.form", "parse_assignment"),
     "parse_full_assignment": ("krons.work.form", "parse_full_assignment"),
-    # phrase
-    "CrudOperation": ("krons.work.phrase", "CrudOperation"),
-    "CrudPattern": ("krons.work.phrase", "CrudPattern"),
-    "Phrase": ("krons.work.phrase", "Phrase"),
-    "phrase": ("krons.work.phrase", "phrase"),
     # report
     "Report": ("krons.work.report", "Report"),
     # worker
@@ -102,16 +96,12 @@ if TYPE_CHECKING:
         parse_assignment,
         parse_full_assignment,
     )
-    from krons.work.phrase import CrudOperation, CrudPattern, Phrase, phrase
     from krons.work.report import Report
     from krons.work.worker import WorkConfig, Worker, WorkLink, work, worklink
 
 __all__ = (
-    "CrudOperation",
-    "CrudPattern",
     "Form",
     "ParsedAssignment",
-    "Phrase",
     "Report",
     "WorkConfig",
     "WorkLink",
@@ -120,7 +110,6 @@ __all__ = (
     "WorkerTask",
     "parse_assignment",
     "parse_full_assignment",
-    "phrase",
     "work",
     "worklink",
 )

{krons-0.2.0 → krons-0.2.2}/src/krons/work/form.py

@@ -6,23 +6,19 @@
 A Form represents an instantiated work unit with:
 - Data binding (input values)
 - Execution state tracking (filled, workable)
-- Optional Phrase reference for typed I/O
 
-Forms are the stateful layer between Phrase (definition) and Operation (execution).
+Forms are the stateful scheduling layer for Operations.
 """
 
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
 from pydantic import Field
 
 from krons.core import Element
 
-if TYPE_CHECKING:
-    from .phrase import Phrase
-
 __all__ = ("Form", "ParsedAssignment", "parse_assignment", "parse_full_assignment")
 
 
@@ -123,9 +119,7 @@ def parse_full_assignment(assignment: str) -> ParsedAssignment:
 class Form(Element):
     """Data binding container for work units.
 
-    A Form binds input data and tracks execution state. It can be created:
-    1. From a Phrase (typed I/O)
-    2. From an assignment string (dynamic fields)
+    A Form binds input data and tracks execution state.
 
     Assignment DSL supports full format:
         "branch: inputs -> outputs | resource"
@@ -144,7 +138,6 @@ class Form(Element):
         available_data: Current data values
         output: Execution result
         filled: Whether form has been executed
-        phrase: Optional Phrase reference for typed execution
     """
 
     assignment: str = Field(
@@ -165,9 +158,6 @@ class Form(Element):
     output: Any = Field(default=None)
     filled: bool = Field(default=False)
 
-    # Optional phrase reference (set via from_phrase())
-    _phrase: "Phrase | None" = None
-
     def model_post_init(self, _: Any) -> None:
         """Parse assignment to derive fields if not already set."""
         if self.assignment and not self.input_fields and not self.output_fields:
@@ -179,35 +169,6 @@ class Form(Element):
             if parsed.resource and self.resource is None:
                 self.resource = parsed.resource
 
-    @classmethod
-    def from_phrase(
-        cls,
-        phrase: "Phrase",
-        **initial_data: Any,
-    ) -> "Form":
-        """Create Form from a Phrase with optional initial data.
-
-        Args:
-            phrase: Phrase defining typed I/O
-            **initial_data: Initial input values
-
-        Returns:
-            Form bound to the phrase
-        """
-        form = cls(
-            assignment=f"{', '.join(phrase.inputs)} -> {', '.join(phrase.outputs)}",
-            input_fields=list(phrase.inputs),
-            output_fields=list(phrase.outputs),
-            available_data=dict(initial_data),
-        )
-        form._phrase = phrase
-        return form
-
-    @property
-    def phrase(self) -> "Phrase | None":
-        """Get bound phrase if any."""
-        return self._phrase
-
     def is_workable(self) -> bool:
         """Check if form is ready for execution.
 
@@ -274,32 +235,8 @@ class Form(Element):
                 result[field] = self.available_data[field]
         return result
 
-    async def execute(self, ctx: Any = None) -> Any:
-        """Execute the form if it has a bound phrase.
-
-        Args:
-            ctx: Execution context
-
-        Returns:
-            Execution result
-
-        Raises:
-            RuntimeError: If no phrase bound or form not workable
-        """
-        if self._phrase is None:
-            raise RuntimeError("Form has no bound phrase - cannot execute")
-
-        if not self.is_workable():
-            missing = [f for f in self.input_fields if f not in self.available_data]
-            raise RuntimeError(f"Form not workable - missing inputs: {missing}")
-
-        result = await self._phrase(self.get_inputs(), ctx)
-        self.set_output(result)
-        return result
-
     def __repr__(self) -> str:
         status = (
             "filled" if self.filled else ("ready" if self.is_workable() else "pending")
         )
-        phrase_info = f", phrase={self._phrase.name}" if self._phrase else ""
-        return f"Form('{self.assignment}', {status}{phrase_info})"
+        return f"Form('{self.assignment}', {status})"

krons-0.2.2/tests/core/test_log.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for krons.core.base.log - DataLoggerConfig."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from krons.core.base.log import DataLoggerConfig
+
+
+class TestDataLoggerConfig:
+    """Tests for DataLoggerConfig."""
+
+    def test_defaults(self):
+        """Config should have sensible defaults."""
+        config = DataLoggerConfig()
+        assert config.persist_dir == "./logs"
+        assert config.extension == ".jsonl"
+        assert config.auto_save_on_exit is True
+
+    def test_custom_values(self):
+        """Config should accept custom values."""
+        config = DataLoggerConfig(
+            persist_dir="/tmp/custom_logs",
+            extension=".json",
+            auto_save_on_exit=False,
+        )
+        assert config.persist_dir == "/tmp/custom_logs"
+        assert config.extension == ".json"
+        assert config.auto_save_on_exit is False
+
+    def test_extension_validation(self):
+        """Config should only accept .json or .jsonl."""
+        with pytest.raises(Exception):
+            DataLoggerConfig(extension=".csv")
+
+    def test_persist_dir_as_path(self):
+        """Config should accept Path object for persist_dir."""
+        config = DataLoggerConfig(persist_dir=Path("/tmp/logs"))
+        assert config.persist_dir == Path("/tmp/logs")