krons 0.2.3__tar.gz → 0.2.4__tar.gz

krons-0.2.4/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.4] - 2026-02-04
+
+### Added
+
+- `parse_forward_ref` canonical parser for ForwardRef annotations
+- Support for `FK["Model"]` and `FK['Model']` string forward references
+- Robust nullability detection: `Optional[X]`, `Union[X, None]`, `X | None`
+- `meta_key` parameter in `ContentSpecs.get_specs()` for DB alias customization
+- Duck typing (`_is_spec_like`) to avoid circular imports
+
+### Changed
+
+- DDL generation now uses config-driven audit columns (dict pattern)
+- `_utils.py` uses shared `parse_forward_ref` instead of duplicate implementation
+- Removed `include_audit_columns` parameter from `generate_ddl()` (now config-driven)
+
+### Fixed
+
+- ForwardRef parsing with `from __future__ import annotations` (PEP 563)
+- Nested Union types in nullability detection (e.g., `Union[FK[User], None]`)
+
+## [0.2.3] - 2026-02-04
+
+### Added
+
+- Multi-agent example patterns (code_review_panel, tech_debate)
+- 10 comprehensive examples demonstrating framework capabilities
+
+### Fixed
+
+- Pile UUID access bug for Element retrieval

{krons-0.2.3 → krons-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: krons
-Version: 0.2.3
+Version: 0.2.4
 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.3 → krons-0.2.4}/pyproject.toml

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

{krons-0.2.3 → krons-0.2.4}/src/krons/agent/message/common.py

@@ -2,7 +2,7 @@ from typing import Any, Protocol, runtime_checkable
 
 from pydantic import BaseModel
 
-from krons.core.types import Enum, MaybeUnset, Unset
+from krons.core.types import Enum
 
 
 @runtime_checkable

{krons-0.2.3 → krons-0.2.4}/src/krons/agent/message/prepare_msg.py

@@ -1,8 +1,7 @@
 # Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
 # SPDX-License-Identifier: Apache-2.0
 
-from collections.abc import Callable
-from typing import TYPE_CHECKING, Any, Literal, cast
+from typing import Any, cast
 
 from pydantic import JsonValue
 

{krons-0.2.3 → krons-0.2.4}/src/krons/core/base/node.py

@@ -745,9 +745,12 @@ def create_node(
         has_embedding = True
 
     # 1. Build all possible specs
+    # Extract meta_key from config_kwargs if provided, else use default
+    meta_key = config_kwargs.get("meta_key", "node_metadata")
     all_specs = ContentSpecs.get_specs(
         content_type=content if content else Unset,
         dim=resolved_embedding_dim,
+        meta_key=meta_key,
     ) + AuditSpecs.get_specs(use_uuid=True)
 
     # 2. Track which fields to include
@@ -837,19 +840,17 @@ def _extract_base_type(annotation: Any) -> Any:
     return annotation
 
 
-def generate_ddl(
-    node_cls: type[Node],
-    *,
-    include_audit_columns: bool = True,
-) -> str:
+def generate_ddl(node_cls: type[Node]) -> str:
     """Generate CREATE TABLE DDL from Node subclass.
 
     Flattens content fields (if configured), adds audit columns, and
     generates PostgreSQL DDL with pgvector support for embeddings.
 
+    Audit column inclusion is driven by NodeConfig settings (track_updated_at,
+    soft_delete, versioning, etc.).
+
     Args:
         node_cls: Persistable Node subclass (must have table_name)
-        include_audit_columns: Include audit columns from NodeConfig
 
     Returns:
         CREATE TABLE IF NOT EXISTS statement
@@ -875,7 +876,8 @@ def generate_ddl(
     )
 
     all_specs = ContentSpecs.get_specs(
-        dim=config.embedding_dim if config.embedding_enabled else Unset
+        dim=config.embedding_dim if config.embedding_enabled else Unset,
+        meta_key=config.meta_key,
     ) + AuditSpecs.get_specs(use_uuid=True)
 
     # Flatten content: extract fields from BaseModel instead of generic JSONB
@@ -900,25 +902,24 @@ def generate_ddl(
     ):
         include.add("content")
 
-    include.add("metadata")
-
-    if include_audit_columns:
-        if config.track_updated_at:
-            include.add("updated_at")
-        if config.track_updated_by:
-            include.add("updated_by")
-        if config.track_is_active:
-            include.add("is_active")
-        if config.soft_delete:
-            include.update({"is_deleted", "deleted_at"})
-            if config.track_deleted_by:
-                include.add("deleted_by")
-        if config.versioning:
-            include.add("version")
-        if config.content_hashing:
-            include.add("content_hash")
-        if config.integrity_hashing:
-            include.add("integrity_hash")
+    if not config.is_sentinel_field("meta_key") and config.meta_key != "metadata":
+        include.add(config.meta_key)
+
+    audit_cols = {
+        "updated_at": config.track_updated_at,
+        "updated_by": config.track_updated_by,
+        "is_active": config.track_is_active,
+        "is_deleted": config.soft_delete,
+        "deleted_at": config.soft_delete,
+        "deleted_by": config.soft_delete and config.track_deleted_by,
+        "version": config.versioning,
+        "content_hash": config.content_hashing,
+        "integrity_hash": config.integrity_hashing,
+    }
+
+    for col, enabled in audit_cols.items():
+        if enabled:
+            include.add(col)
 
     # If flattened, include the extracted content field names
     if config.flatten_content and content_type is not None:

krons-0.2.4/src/krons/core/specs/adapters/_utils.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import types
+from functools import reduce
+from typing import Annotated, Any, ForwardRef, Union, get_args, get_origin
+from uuid import UUID
+
+
+def _resolve_forward_ref(fwd: ForwardRef) -> dict[str, Any]:
+    """Handle ForwardRef annotations (from 'from __future__ import annotations').
+
+    Parses the string representation to extract type info for DDL generation.
+    FK[Model] -> Annotated[UUID, FKMeta(model_name)], Vector[dim] -> list[float], etc.
+
+    Uses parse_forward_ref from db_types as canonical parser.
+    """
+    from krons.core.types.db_types import parse_forward_ref
+
+    fk, vec, nullable = parse_forward_ref(fwd)
+
+    # FK[Model] -> Annotated[UUID, FKMeta]
+    if fk is not None:
+        base_type = Annotated[UUID, fk]
+        return {"base_type": base_type, "nullable": nullable, "listable": False}
+
+    # Vector[dim] -> Annotated[list[float], VectorMeta]
+    if vec is not None:
+        base_type = Annotated[list[float], vec]
+        return {"base_type": base_type, "nullable": nullable, "listable": False}
+
+    # Default: treat as generic type (will map to TEXT in SQL)
+    return {"base_type": str, "nullable": nullable, "listable": False}
+
+
+def resolve_annotation_to_base_types(annotation: Any) -> dict[str, Any]:
+    """Resolve an annotation to its base types, detecting nullable and listable.
+
+    Args:
+        annotation: Type annotation to resolve (may include Optional, list, etc.)
+
+    Returns:
+        Dict with keys:
+            - base_type: The innermost type
+            - nullable: Whether None is allowed
+            - listable: Whether it's a list type
+    """
+    # Handle ForwardRef (from 'from __future__ import annotations')
+    if isinstance(annotation, ForwardRef):
+        return _resolve_forward_ref(annotation)
+
+    def resolve_nullable_inner_type(_anno: Any) -> tuple[bool, Any]:
+        origin = get_origin(_anno)
+
+        if origin is type(None):
+            return True, type(None)
+
+        if origin in (type(int | str), types.UnionType) or origin is Union:
+            args = get_args(_anno)
+            non_none_args = [a for a in args if a is not type(None)]
+            if len(args) != len(non_none_args):
+                if len(non_none_args) == 1:
+                    return True, non_none_args[0]
+                if non_none_args:
+                    return True, reduce(lambda a, b: a | b, non_none_args)
+            return False, _anno
+
+        return False, _anno
+
+    def resolve_listable_element_type(_anno: Any) -> Any:
+        origin = get_origin(_anno)
+
+        if origin is list:
+            args = get_args(_anno)
+            if args:
+                return True, args[0]
+            return True, Any
+
+        return False, _anno
+
+    _null, _inner = resolve_nullable_inner_type(annotation)
+    _list, _elem = resolve_listable_element_type(_inner)
+
+    return {
+        "base_type": _elem,
+        "nullable": _null,
+        "listable": _list,
+    }

{krons-0.2.3 → krons-0.2.4}/src/krons/core/specs/catalog/_content.py

@@ -33,12 +33,14 @@ class ContentSpecs(BaseModel):
         *,
         content_type: type | UnsetType = Unset,
         dim: int | UnsetType = Unset,
+        meta_key: str | UnsetType = Unset,
     ) -> list[Spec]:
         """Get list of content Specs.
 
         Args:
             content_type: Type for content/metadata fields (default: dict).
             dim: Embedding dimension. Unset = list[float], int = Vector[dim].
+            meta_key: DB alias for metadata field (e.g., "node_metadata").
         """
         operable = Operable.from_structure(cls)
         specs = {spec.name: spec for spec in operable.get_specs()}
@@ -48,6 +50,10 @@ class ContentSpecs(BaseModel):
             specs["content"] = Spec(content_type, name="content").as_nullable()
             specs["metadata"] = Spec(content_type, name="metadata").as_nullable()
 
+        # Add meta_key alias if specified (DB mode uses this to avoid SQL reserved word)
+        if meta_key is not Unset and isinstance(meta_key, str):
+            specs[meta_key] = Spec(dict[str, Any], name=meta_key).as_nullable()
+
         # Override embedding with vector dimension if specified
         if dim is not Unset and isinstance(dim, int):
             specs["embedding"] = Spec(

{krons-0.2.3 → krons-0.2.4}/src/krons/core/types/db_types.py

@@ -14,8 +14,9 @@ Extraction:
 
 from __future__ import annotations
 
+import re
 import types
-from typing import Annotated, Any, Literal, Union, get_args, get_origin
+from typing import Annotated, Any, ForwardRef, Literal, Union, get_args, get_origin
 from uuid import UUID
 
 from krons.core.types._sentinel import Unset, UnsetType, not_sentinel
@@ -32,6 +33,7 @@ __all__ = [
     "Vector",
     "VectorMeta",
     "extract_kron_db_meta",
+    "parse_forward_ref",
 ]
 
 
@@ -200,6 +202,88 @@ def _find_in_field_info(field_info: Any, meta_type: type) -> Any | None:
     return None
 
 
+def _is_spec_like(obj: Any) -> bool:
+    """Check if object looks like a Spec (duck typing to avoid hard import)."""
+    return (
+        hasattr(obj, "get")
+        and hasattr(obj, "__class__")
+        and "Spec" in type(obj).__name__
+    )
+
+
+def _detect_nullable(arg: str) -> bool:
+    """Detect nullability from annotation string.
+
+    Handles:
+        - X | None, None | X (PEP 604 union)
+        - Optional[X] (typing.Optional)
+        - Union[X, None], Union[None, X] (typing.Union with nested types)
+    """
+    # PEP 604 style: X | None or None | X
+    if re.search(r"\|\s*None\b", arg) or re.search(r"\bNone\s*\|", arg):
+        return True
+    # Optional[X]
+    if re.search(r"\bOptional\s*\[", arg):
+        return True
+    # Union[..., None, ...] - if Union is present and None is anywhere in string
+    # This handles nested types like Union[FK[User], None]
+    if re.search(r"\bUnion\s*\[", arg) and re.search(r"\bNone\b", arg):
+        return True
+    return False
+
+
+def parse_forward_ref(
+    fwd: ForwardRef,
+) -> tuple[FKMeta | None, VectorMeta | None, bool]:
+    """Parse FK/Vector metadata and nullability from a ForwardRef string.
+
+    Canonical parser for ForwardRef annotations from 'from __future__ import annotations'.
+
+    Handles:
+        - FK[Model], FK["Model"], FK['Model'] (bare and string refs)
+        - Vector[1536] (dimension as int literal)
+        - Nullability: X | None, Optional[X], Union[X, None]
+
+    Args:
+        fwd: ForwardRef to parse
+
+    Returns:
+        Tuple of (fk_meta, vector_meta, is_nullable)
+        - fk_meta: FKMeta if FK[...] found, else None
+        - vector_meta: VectorMeta if Vector[dim] found, else None
+        - is_nullable: True if nullable pattern detected
+    """
+    arg = fwd.__forward_arg__
+    fk: FKMeta | None = None
+    vec: VectorMeta | None = None
+    nullable = _detect_nullable(arg)
+
+    # Match FK[ModelName] or FK["ModelName"] or FK['ModelName']
+    fk_match = re.search(r"FK\[(['\"]?)(\w+)\1\]", arg)
+    if fk_match:
+        model_name = fk_match.group(2)
+        fk = FKMeta(model_name)
+
+    # Match Vector[dim]
+    vec_match = re.search(r"Vector\[(\d+)\]", arg)
+    if vec_match:
+        dim = int(vec_match.group(1))
+        vec = VectorMeta(dim)
+
+    return fk, vec, nullable
+
+
+def _extract_from_forward_ref(
+    fwd: ForwardRef,
+) -> tuple[FKMeta | UnsetType, VectorMeta | UnsetType]:
+    """Extract FK/Vector metadata from a ForwardRef (returns Unset for missing).
+
+    Wrapper around parse_forward_ref for extract_kron_db_meta compatibility.
+    """
+    fk, vec, _ = parse_forward_ref(fwd)
+    return (fk if fk is not None else Unset, vec if vec is not None else Unset)
+
+
 def extract_kron_db_meta(
     from_: Any,
     metas: Literal["FK", "Vector", "BOTH"] = "BOTH",
@@ -209,7 +293,7 @@ def extract_kron_db_meta(
     Unified extraction dispatching on source type:
     - FieldInfo: searches Pydantic metadata and annotation
     - type/annotation: searches Annotated/Union structure
-    - Spec: reads spec metadata directly
+    - Spec: reads spec metadata directly (if available)
 
     Args:
         from_: FieldInfo, type annotation, or Spec instance
@@ -228,6 +312,10 @@ def extract_kron_db_meta(
         if metas in ("Vector", "BOTH"):
             vec = _find_in_field_info(from_, VectorMeta) or Unset
 
+    elif isinstance(from_, ForwardRef):
+        # Handle ForwardRef from 'from __future__ import annotations'
+        fk, vec = _extract_from_forward_ref(from_)
+
     elif get_origin(from_) is not None or isinstance(from_, type):
         # Raw type annotation
         if metas in ("FK", "BOTH"):
@@ -235,23 +323,20 @@ def extract_kron_db_meta(
         if metas in ("Vector", "BOTH"):
             vec = _find_in_annotation(from_, VectorMeta) or Unset
 
+    elif _is_spec_like(from_):
+        # Spec-like object (duck typed to avoid circular imports)
+        if metas in ("FK", "BOTH"):
+            fk_val = from_.get("as_fk", Unset)
+            if not_sentinel(fk_val, {"none"}) and isinstance(fk_val, FKMeta):
+                fk = fk_val
+        if metas in ("Vector", "BOTH"):
+            vec_val = from_.get("embedding", Unset)
+            if not_sentinel(vec_val, {"none"}) and isinstance(vec_val, VectorMeta):
+                vec = vec_val
     else:
-        # Try Spec (lazy import to avoid circular)
-        from krons.core.specs.spec import Spec
-
-        if isinstance(from_, Spec):
-            if metas in ("FK", "BOTH"):
-                fk_val = from_.get("as_fk", Unset)
-                if not_sentinel(fk_val, {"none"}) and isinstance(fk_val, FKMeta):
-                    fk = fk_val
-            if metas in ("Vector", "BOTH"):
-                vec_val = from_.get("embedding", Unset)
-                if not_sentinel(vec_val, {"none"}) and isinstance(vec_val, VectorMeta):
-                    vec = vec_val
-        else:
-            raise TypeError(
-                f"from_ must be FieldInfo, type annotation, or Spec, got {type(from_).__name__}"
-            )
+        raise TypeError(
+            f"from_ must be FieldInfo, type annotation, or Spec, got {type(from_).__name__}"
+        )
 
     if metas == "FK":
         return fk

{krons-0.2.3 → krons-0.2.4}/src/krons/session/session.py

@@ -84,7 +84,9 @@ class Session(Element):
         default_factory=lambda: Flow(item_type=Message)
     )
     resources: ResourceRegistry = Field(default_factory=ResourceRegistry, exclude=True)
-    operations: OperationRegistry = Field(default_factory=OperationRegistry, exclude=True)
+    operations: OperationRegistry = Field(
+        default_factory=OperationRegistry, exclude=True
+    )
     config: SessionConfig = Field(default_factory=SessionConfig)
     default_branch_id: UUID | None = None
 

{krons-0.2.3 → krons-0.2.4}/tests/specs/test_catalog.py

@@ -108,6 +108,16 @@ class TestContentSpecs:
         assert "metadata" in names
         assert "embedding" in names
 
+    def test_get_specs_with_meta_key(self):
+        """ContentSpecs with meta_key should include the alias."""
+        specs = ContentSpecs.get_specs(meta_key="node_metadata")
+
+        assert isinstance(specs, list)
+        assert len(specs) == 6
+
+        names = [s.name for s in specs]
+        assert "node_metadata" in names
+
     def test_get_specs_id_is_uuid(self):
         """ID spec should be UUID type."""
         specs = ContentSpecs.get_specs()

{krons-0.2.3 → krons-0.2.4}/tests/types/test_db_types.py

@@ -3,13 +3,14 @@
 
 """Tests for database type annotations (FK, Vector)."""
 
-from typing import Annotated, get_args, get_origin
+from typing import Annotated, ForwardRef, get_args, get_origin
 from uuid import UUID
 
 import pytest
 from pydantic import BaseModel, Field
 
 from krons.core.types import FK, FKMeta, Unset, Vector, VectorMeta, extract_kron_db_meta
+from krons.core.types.db_types import parse_forward_ref
 
 
 class MockTenant:
@@ -236,3 +237,118 @@ class TestVectorMetaExtraction:
         meta = extract_kron_db_meta(field_info, metas="Vector")
 
         assert meta is Unset
+
+
+class TestParseForwardRef:
+    """Tests for parse_forward_ref canonical parser."""
+
+    # --- FK patterns ---
+
+    def test_fk_bare_model(self):
+        """Should parse FK[Model]."""
+        fwd = ForwardRef("FK[User]")
+        fk, vec, nullable = parse_forward_ref(fwd)
+
+        assert fk is not None
+        assert fk.model == "User"
+        assert vec is None
+        assert not nullable
+
+    def test_fk_string_double_quotes(self):
+        """Should parse FK["Model"] with double quotes."""
+        fwd = ForwardRef('FK["User"]')
+        fk, vec, nullable = parse_forward_ref(fwd)
+
+        assert fk is not None
+        assert fk.model == "User"
+
+    def test_fk_string_single_quotes(self):
+        """Should parse FK['Model'] with single quotes."""
+        fwd = ForwardRef("FK['User']")
+        fk, vec, nullable = parse_forward_ref(fwd)
+
+        assert fk is not None
+        assert fk.model == "User"
+
+    # --- Vector patterns ---
+
+    def test_vector_dimension(self):
+        """Should parse Vector[1536]."""
+        fwd = ForwardRef("Vector[1536]")
+        fk, vec, nullable = parse_forward_ref(fwd)
+
+        assert fk is None
+        assert vec is not None
+        assert vec.dim == 1536
+        assert not nullable
+
+    # --- Nullability: PEP 604 style ---
+
+    def test_nullable_pipe_none_suffix(self):
+        """Should detect X | None."""
+        fwd = ForwardRef("FK[User] | None")
+        fk, vec, nullable = parse_forward_ref(fwd)
+
+        assert fk is not None
+        assert nullable
+
+    def test_nullable_none_pipe_prefix(self):
+        """Should detect None | X."""
+        fwd = ForwardRef("None | FK[User]")
+        fk, vec, nullable = parse_forward_ref(fwd)
+
+        assert fk is not None
+        assert nullable
+
+    # --- Nullability: Optional style ---
+
+    def test_nullable_optional(self):
+        """Should detect Optional[X]."""
+        fwd = ForwardRef("Optional[FK[User]]")
+        fk, vec, nullable = parse_forward_ref(fwd)
+
+        assert fk is not None
+        assert nullable
+
+    # --- Nullability: Union style ---
+
+    def test_nullable_union_none_last(self):
+        """Should detect Union[X, None]."""
+        fwd = ForwardRef("Union[FK[User], None]")
+        fk, vec, nullable = parse_forward_ref(fwd)
+
+        assert fk is not None
+        assert nullable
+
+    def test_nullable_union_none_first(self):
+        """Should detect Union[None, X]."""
+        fwd = ForwardRef("Union[None, FK[User]]")
+        fk, vec, nullable = parse_forward_ref(fwd)
+
+        assert fk is not None
+        assert nullable
+
+    # --- Non-nullable cases ---
+
+    def test_not_nullable_plain(self):
+        """Plain type should not be nullable."""
+        fwd = ForwardRef("FK[User]")
+        _, _, nullable = parse_forward_ref(fwd)
+        assert not nullable
+
+    def test_not_nullable_union_without_none(self):
+        """Union without None should not be nullable."""
+        fwd = ForwardRef("Union[FK[User], FK[Tenant]]")
+        _, _, nullable = parse_forward_ref(fwd)
+        assert not nullable
+
+    # --- Unknown patterns ---
+
+    def test_unknown_type_returns_none(self):
+        """Unknown type should return None for FK and Vector."""
+        fwd = ForwardRef("SomeRandomType")
+        fk, vec, nullable = parse_forward_ref(fwd)
+
+        assert fk is None
+        assert vec is None
+        assert not nullable

{krons-0.2.3 → krons-0.2.4}/uv.lock

@@ -889,7 +889,7 @@ wheels = [
 
 [[package]]
 name = "krons"
-version = "0.2.2"
+version = "0.2.3"
 source = { editable = "." }
 dependencies = [
     { name = "anyio" },

krons-0.2.3/src/krons/core/specs/adapters/_utils.py

@@ -1,45 +0,0 @@
-from __future__ import annotations
-
-import types
-from functools import reduce
-from typing import Any, Union, get_args, get_origin
-
-
-def resolve_annotation_to_base_types(annotation: Any) -> dict[str, Any]:
-    def resolve_nullable_inner_type(_anno: Any) -> tuple[bool, Any]:
-        origin = get_origin(_anno)
-
-        if origin is type(None):
-            return True, type(None)
-
-        if origin in (type(int | str), types.UnionType) or origin is Union:
-            args = get_args(_anno)
-            non_none_args = [a for a in args if a is not type(None)]
-            if len(args) != len(non_none_args):
-                if len(non_none_args) == 1:
-                    return True, non_none_args[0]
-                if non_none_args:
-                    return True, reduce(lambda a, b: a | b, non_none_args)
-            return False, _anno
-
-        return False, _anno
-
-    def resolve_listable_element_type(_anno: Any) -> Any:
-        origin = get_origin(_anno)
-
-        if origin is list:
-            args = get_args(_anno)
-            if args:
-                return True, args[0]
-            return True, Any
-
-        return False, _anno
-
-    _null, _inner = resolve_nullable_inner_type(annotation)
-    _list, _elem = resolve_listable_element_type(_inner)
-
-    return {
-        "base_type": _elem,
-        "nullable": _null,
-        "listable": _list,
-    }