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

krons/core/{node.py → base/node.py}

@@ -15,8 +15,7 @@ from uuid import UUID
 
 from pydantic import BaseModel, field_serializer, field_validator
 
-from krons.protocols import Deserializable, Serializable, implements
-from krons.types import (
+from krons.core.types import (
     ModelConfig,
     Params,
     Unset,
@@ -25,7 +24,8 @@ from krons.types import (
     is_unset,
     not_sentinel,
 )
-from krons.types.db_types import VectorMeta, extract_kron_db_meta
+from krons.core.types.db_types import VectorMeta, extract_kron_db_meta
+from krons.protocols import Deserializable, Serializable, implements
 from krons.utils import compute_hash, json_dump, now_utc
 
 from .element import Element
@@ -56,9 +56,13 @@ def _enable_embedding_requires_dim(config: NodeConfig) -> None:
     """Validate: embedding_enabled requires positive embedding_dim."""
     if config.embedding_enabled:
         if config.is_sentinel_field("embedding_dim"):
-            raise ValueError("embedding_dim must be specified when embedding is enabled")
+            raise ValueError(
+                "embedding_dim must be specified when embedding is enabled"
+            )
         if config.embedding_dim <= 0:
-            raise ValueError(f"embedding_dim must be positive, got {config.embedding_dim}")
+            raise ValueError(
+                f"embedding_dim must be positive, got {config.embedding_dim}"
+            )
 
 
 def _only_typed_content_can_flatten(config: NodeConfig) -> None:
@@ -231,7 +235,9 @@ class Node(Element):
                 cls._resolved_content_type = None
         else:
             cls._resolved_content_type = (
-                None if config.is_sentinel_field("content_type") else config.content_type
+                None
+                if config.is_sentinel_field("content_type")
+                else config.content_type
             )
 
     @field_serializer("content")
@@ -263,7 +269,10 @@ class Node(Element):
             metadata = value.get("metadata", {})
             kron_class = metadata.get("kron_class")
             if kron_class:
-                if kron_class in NODE_REGISTRY or kron_class.split(".")[-1] in NODE_REGISTRY:
+                if (
+                    kron_class in NODE_REGISTRY
+                    or kron_class.split(".")[-1] in NODE_REGISTRY
+                ):
                     return Node.from_dict(value)
                 return Element.from_dict(value)
         return value
@@ -271,7 +280,9 @@ class Node(Element):
     def to_dict(
         self,
         mode: Literal["python", "json", "db"] = "python",
-        created_at_format: (Literal["datetime", "isoformat", "timestamp"] | UnsetType) = Unset,
+        created_at_format: (
+            Literal["datetime", "isoformat", "timestamp"] | UnsetType
+        ) = Unset,
         meta_key: str | UnsetType = Unset,
         content_serializer: Callable[[Any], Any] | None = None,
         **kwargs: Any,
@@ -421,14 +432,18 @@ class Node(Element):
                 and issubclass(content_type, BaseModel)
             ):
                 content_field_names = set(content_type.model_fields.keys())
-                content_data = {k: v for k, v in data.items() if k in content_field_names}
+                content_data = {
+                    k: v for k, v in data.items() if k in content_field_names
+                }
                 for k in content_field_names:
                     data.pop(k, None)
                 data["content"] = content_type(**content_data)
 
         # Handle meta_key for DB rows
         effective_meta_key = (
-            meta_key if not is_unset(meta_key) else (config.meta_key if from_row else Unset)
+            meta_key
+            if not is_unset(meta_key)
+            else (config.meta_key if from_row else Unset)
         )
 
         if content_deserializer is not None:
@@ -704,8 +719,8 @@ def create_node(
         >>> Job = create_node("Job", embedding_enabled=True, embedding_dim=1536)
 
     """
-    from krons.specs.catalog import AuditSpecs, ContentSpecs
-    from krons.specs.operable import Operable
+    from krons.core.specs.catalog import AuditSpecs, ContentSpecs
+    from krons.core.specs.operable import Operable
 
     # Resolve embedding dimension
     resolved_embedding_dim: int | UnsetType = Unset
@@ -723,7 +738,9 @@ def create_node(
             )
     elif embedding_enabled:
         if embedding_dim is None or embedding_dim <= 0:
-            raise ValueError("embedding_dim must be positive when embedding_enabled=True")
+            raise ValueError(
+                "embedding_dim must be positive when embedding_enabled=True"
+            )
         resolved_embedding_dim = embedding_dim
         has_embedding = True
 
@@ -742,7 +759,11 @@ def create_node(
         include.append("embedding")
 
     needs_update_tracking = (
-        track_updated_at or content_hashing or integrity_hashing or soft_delete or versioning
+        track_updated_at
+        or content_hashing
+        or integrity_hashing
+        or soft_delete
+        or versioning
     )
     if needs_update_tracking:
         include.append("updated_at")
@@ -805,7 +826,9 @@ def _extract_base_type(annotation: Any) -> Any:
     if annotation is None:
         return None
 
-    if isinstance(annotation, types.UnionType) or get_origin(annotation) is type(int | str):
+    if isinstance(annotation, types.UnionType) or get_origin(annotation) is type(
+        int | str
+    ):
         args = get_args(annotation)
         non_none_args = [a for a in args if a is not type(None)]
         if non_none_args:
@@ -835,12 +858,14 @@ def generate_ddl(
         ValueError: If node_cls has no table_name configured
 
     """
-    from krons.specs.catalog import AuditSpecs, ContentSpecs
-    from krons.specs.operable import Operable
+    from krons.core.specs.catalog import AuditSpecs, ContentSpecs
+    from krons.core.specs.operable import Operable
 
     config = node_cls.get_config()
     if not config.is_persisted:
-        raise ValueError(f"{node_cls.__name__} is not persistable (no table_name configured)")
+        raise ValueError(
+            f"{node_cls.__name__} is not persistable (no table_name configured)"
+        )
 
     # 1. Build all possible specs for this node
     content_type = (
@@ -855,7 +880,7 @@ def generate_ddl(
 
     # Flatten content: extract fields from BaseModel instead of generic JSONB
     if config.flatten_content and content_type is not None:
-        from krons.specs.adapters.pydantic_adapter import PydanticSpecAdapter
+        from krons.core.specs.adapters.pydantic_adapter import PydanticSpecAdapter
 
         if isinstance(content_type, type) and issubclass(content_type, BaseModel):
             all_specs.extend(PydanticSpecAdapter.extract_specs(content_type))

krons/core/{pile.py → base/pile.py}

@@ -12,9 +12,9 @@ from uuid import UUID
 from pydantic import Field, PrivateAttr, field_serializer, field_validator
 from typing_extensions import override
 
+from krons.core.types import Unset, UnsetType, is_unset
 from krons.errors import ExistsError, NotFoundError
 from krons.protocols import Containable, Deserializable, Serializable, implements
-from krons.types import Unset, UnsetType, is_unset
 from krons.utils import extract_types, load_type_from_string, synchronized
 from krons.utils.concurrency import Lock as AsyncLock
 
@@ -59,7 +59,9 @@ class Pile(Element, Generic[T]):
     @property
     def progression(self) -> Progression:
         """Read-only copy of progression order."""
-        return Progression(order=list(self._progression.order), name=self._progression.name)
+        return Progression(
+            order=list(self._progression.order), name=self._progression.name
+        )
 
     item_type: set[type] | None = Field(
         default=None,
@@ -104,7 +106,9 @@ class Pile(Element, Generic[T]):
             NotFoundError: If order contains UUID not in items
             TypeError: If item type validation fails
         """
-        super().__init__(**{"item_type": item_type, "strict_type": strict_type, **kwargs})
+        super().__init__(
+            **{"item_type": item_type, "strict_type": strict_type, **kwargs}
+        )
 
         if items:
             for item in items:
@@ -128,10 +132,14 @@ class Pile(Element, Generic[T]):
     def to_dict(
         self,
         mode: Literal["python", "json", "db"] = "python",
-        created_at_format: (Literal["datetime", "isoformat", "timestamp"] | UnsetType) = Unset,
+        created_at_format: (
+            Literal["datetime", "isoformat", "timestamp"] | UnsetType
+        ) = Unset,
         meta_key: str | UnsetType = Unset,
         item_meta_key: str | UnsetType = Unset,
-        item_created_at_format: (Literal["datetime", "isoformat", "timestamp"] | UnsetType) = Unset,
+        item_created_at_format: (
+            Literal["datetime", "isoformat", "timestamp"] | UnsetType
+        ) = Unset,
         **kwargs: Any,
     ) -> dict[str, Any]:
         """Serialize pile with items in progression order.
@@ -350,7 +358,9 @@ class Pile(Element, Generic[T]):
                 raise TypeError("Cannot mix int and UUID in list/tuple indexing")
             items = [self.get(uid) for uid in keys]
         else:
-            raise TypeError(f"list/tuple must contain only int or UUID, got {type(first)}")
+            raise TypeError(
+                f"list/tuple must contain only int or UUID, got {type(first)}"
+            )
 
         return Pile(
             items=items,
@@ -530,7 +540,9 @@ class Pile(Element, Generic[T]):
                 and item_type_data
                 and isinstance(item_type_data[0], str)
             ):
-                allowed_types = {load_type_from_string(type_str) for type_str in item_type_data}
+                allowed_types = {
+                    load_type_from_string(type_str) for type_str in item_type_data
+                }
             else:
                 allowed_types = extract_types(item_type_data)
 
@@ -549,7 +561,9 @@ class Pile(Element, Generic[T]):
                                 "(strict_type=True)"
                             )
                     else:
-                        if not any(issubclass(item_type_actual, t) for t in allowed_types):
+                        if not any(
+                            issubclass(item_type_actual, t) for t in allowed_types
+                        ):
                             raise TypeError(
                                 f"Item type {kron_class} is not a subclass of any allowed type {allowed_types}"
                             )

krons/core/{processor.py → base/processor.py}

@@ -77,13 +77,19 @@ class Processor:
         if queue_capacity < 1:
             raise ValueError("Queue capacity must be greater than 0.")
         if queue_capacity > 10000:
-            raise ValueError("Queue capacity must be <= 10000 (prevent unbounded batches).")
+            raise ValueError(
+                "Queue capacity must be <= 10000 (prevent unbounded batches)."
+            )
 
         # Validate capacity_refresh_time (prevent hot loop or starvation)
         if capacity_refresh_time < 0.01:
-            raise ValueError("Capacity refresh time must be >= 0.01s (prevent CPU hot loop).")
+            raise ValueError(
+                "Capacity refresh time must be >= 0.01s (prevent CPU hot loop)."
+            )
         if capacity_refresh_time > 3600:
-            raise ValueError("Capacity refresh time must be <= 3600s (prevent starvation).")
+            raise ValueError(
+                "Capacity refresh time must be <= 3600s (prevent starvation)."
+            )
 
         # Validate concurrency_limit
         if concurrency_limit < 1:
@@ -105,7 +111,9 @@ class Processor:
         self.concurrency_limit = concurrency_limit
 
         # Priority queue: (priority, event_uuid) tuples, min-heap ordering
-        self.queue: concurrency.PriorityQueue[tuple[float, UUID]] = concurrency.PriorityQueue()
+        self.queue: concurrency.PriorityQueue[tuple[float, UUID]] = (
+            concurrency.PriorityQueue()
+        )
 
         self._available_capacity = queue_capacity
         self._execution_mode = False
@@ -231,7 +239,9 @@ class Processor:
                     self._denial_counts.pop(event_id, None)
 
                     if self.executor:
-                        await self.executor._update_progression(next_event, EventStatus.PROCESSING)
+                        await self.executor._update_progression(
+                            next_event, EventStatus.PROCESSING
+                        )
 
                     if next_event.streaming:
 
@@ -255,7 +265,9 @@ class Processor:
                                 if self.executor:
                                     await self.executor._update_progression(event)
 
-                        tg.start_soon(self._with_semaphore, invoke_and_update(next_event))
+                        tg.start_soon(
+                            self._with_semaphore, invoke_and_update(next_event)
+                        )
 
                     events_processed += 1
                     self._available_capacity -= 1
@@ -270,7 +282,9 @@ class Processor:
 
                     if denial_count >= 3:
                         if self.executor:
-                            await self.executor._update_progression(next_event, EventStatus.ABORTED)
+                            await self.executor._update_progression(
+                                next_event, EventStatus.ABORTED
+                            )
                         self._denial_counts.pop(event_id, None)
                     else:
                         backoff = denial_count * 1.0

krons/core/{progression.py → base/progression.py}

@@ -177,7 +177,9 @@ class Progression(Element):
         """Set item(s) at index. Slice assignment requires list value."""
         if isinstance(index, slice):
             if not isinstance(value, list):
-                raise TypeError(f"Cannot assign {type(value).__name__} to slice, expected list")
+                raise TypeError(
+                    f"Cannot assign {type(value).__name__} to slice, expected list"
+                )
             new_uids = [self._coerce_id(v) for v in value]
             self.order[index] = new_uids
             self._rebuild_members()

krons/{specs → core/specs}/__init__.py

@@ -4,7 +4,6 @@
 from .adapters.factory import AdapterType, get_adapter
 from .catalog import AuditSpecs, CommonSpecs, ContentSpecs
 from .operable import Operable
-from .phrase import CrudOperation, CrudPattern, Phrase, phrase
 from .protocol import SpecAdapter
 from .spec import CommonMeta, Spec
 
@@ -14,12 +13,8 @@ __all__ = (
     "CommonMeta",
     "CommonSpecs",
     "ContentSpecs",
-    "CrudOperation",
-    "CrudPattern",
     "Operable",
-    "Phrase",
     "Spec",
     "SpecAdapter",
     "get_adapter",
-    "phrase",
 )

krons/{specs → core/specs}/adapters/dataclass_field.py

@@ -17,14 +17,14 @@ from dataclasses import field as dc_field
 from dataclasses import fields
 from typing import TYPE_CHECKING, Any
 
-from krons.types._sentinel import Unset, UnsetType, is_sentinel
+from krons.core.types._sentinel import Unset, UnsetType, is_sentinel
 
 from ..protocol import SpecAdapter
 from ..spec import Spec
 from ._utils import resolve_annotation_to_base_types
 
 if TYPE_CHECKING:
-    from krons.types.base import DataClass, ModelConfig, Params
+    from krons.core.types.base import DataClass, ModelConfig, Params
 
     from ..operable import Operable
 
@@ -71,7 +71,9 @@ def _make_validator_method(validators: dict[str, list[Any]], is_frozen: bool) ->
                     errors.append(ValueError(f"Validation failed for '{fname}': {e}"))
 
         if errors:
-            raise ExceptionGroup(f"Field validation failed for {type(self).__name__}", errors)
+            raise ExceptionGroup(
+                f"Field validation failed for {type(self).__name__}", errors
+            )
 
     return _validate_with_field_validators
 
@@ -149,7 +151,7 @@ class DataClassSpecAdapter(SpecAdapter[dict[str, Any]]):
         Returns:
             Dynamically created dataclass with validators wired in
         """
-        from krons.types.base import DataClass, Params
+        from krons.core.types.base import DataClass, Params
 
         use_specs = op.get_specs(include=include, exclude=exclude)
 
@@ -176,7 +178,9 @@ class DataClassSpecAdapter(SpecAdapter[dict[str, Any]]):
             annotations[field_name] = spec.annotation
 
             if "default_factory" in field_kwargs:
-                class_attrs[field_name] = dc_field(default_factory=field_kwargs["default_factory"])
+                class_attrs[field_name] = dc_field(
+                    default_factory=field_kwargs["default_factory"]
+                )
             elif "default" in field_kwargs:
                 class_attrs[field_name] = field_kwargs["default"]
 
@@ -221,15 +225,19 @@ class DataClassSpecAdapter(SpecAdapter[dict[str, Any]]):
         return instance.to_dict()
 
     @classmethod
-    def extract_specs(cls, structure: type[Params] | type[DataClass]) -> tuple[Spec, ...]:
+    def extract_specs(
+        cls, structure: type[Params] | type[DataClass]
+    ) -> tuple[Spec, ...]:
         """Extract Specs from DataClass/Params, preserving defaults and type modifiers.
 
         Raises:
             TypeError: If structure is not a DataClass or Params subclass
         """
-        from krons.types.base import DataClass, Params
+        from krons.core.types.base import DataClass, Params
 
-        if not isinstance(structure, type) or not issubclass(structure, (DataClass, Params)):
+        if not isinstance(structure, type) or not issubclass(
+            structure, (DataClass, Params)
+        ):
             raise TypeError(
                 f"structure must be a DataClass or Params subclass, got {type(structure)}"
             )

krons/{specs → core/specs}/adapters/pydantic_adapter.py

@@ -20,15 +20,21 @@ from pydantic.fields import FieldInfo
 from pydantic_core import PydanticUndefined
 from pydantic_core._pydantic_core import PydanticUndefinedType
 
-from krons.specs.protocol import SpecAdapter
-from krons.specs.spec import Spec
-from krons.types._sentinel import Unset, UnsetType, is_sentinel, is_unset, not_sentinel
-from krons.types.db_types import FKMeta, VectorMeta
+from krons.core.specs.protocol import SpecAdapter
+from krons.core.specs.spec import Spec
+from krons.core.types._sentinel import (
+    Unset,
+    UnsetType,
+    is_sentinel,
+    is_unset,
+    not_sentinel,
+)
+from krons.core.types.db_types import FKMeta, VectorMeta
 
 from ._utils import resolve_annotation_to_base_types
 
 if TYPE_CHECKING:
-    from krons.specs.operable import Operable
+    from krons.core.specs.operable import Operable
 
 __all__ = ("PydanticSpecAdapter",)
 

krons/{specs → core/specs}/adapters/sql_ddl.py

@@ -27,16 +27,22 @@ from enum import StrEnum
 from typing import TYPE_CHECKING, Annotated, Any, get_args, get_origin
 from uuid import UUID
 
-from krons.types._sentinel import Unset, UnsetType, is_sentinel
-from krons.types.db_types import FK, FKMeta, Vector, VectorMeta, extract_kron_db_meta
+from krons.core.types._sentinel import Unset, UnsetType, is_sentinel
+from krons.core.types.db_types import (
+    FK,
+    FKMeta,
+    Vector,
+    VectorMeta,
+    extract_kron_db_meta,
+)
 from krons.utils.sql import validate_identifier
 
 from ..protocol import SpecAdapter
 from ._utils import resolve_annotation_to_base_types
 
 if TYPE_CHECKING:
-    from krons.specs.operable import Operable
-    from krons.specs.spec import Spec
+    from krons.core.specs.operable import Operable
+    from krons.core.specs.spec import Spec
 
 __all__ = (
     # Enums
@@ -414,9 +420,7 @@ class UniqueConstraintSpec:
         for col in self.columns:
             validate_identifier(col, "column name")
         cols = ", ".join(f'"{c}"' for c in self.columns)
-        return (
-            f'ALTER TABLE "{schema}"."{table_name}" ADD CONSTRAINT "{self.name}" UNIQUE ({cols});'
-        )
+        return f'ALTER TABLE "{schema}"."{table_name}" ADD CONSTRAINT "{self.name}" UNIQUE ({cols});'
 
 
 @dataclass(frozen=True, slots=True)
@@ -468,7 +472,9 @@ class TableSpec:
         col_lines = col_separator.join(col_defs)
 
         exists_clause = "IF NOT EXISTS " if if_not_exists else ""
-        return f"CREATE TABLE {exists_clause}{self.qualified_name} (\n    {col_lines}\n);"
+        return (
+            f"CREATE TABLE {exists_clause}{self.qualified_name} (\n    {col_lines}\n);"
+        )
 
     def to_full_ddl(self) -> list[str]:
         """Generate all DDL statements for this table.

krons/{specs → core/specs}/catalog/__init__.py

@@ -9,14 +9,14 @@ Pre-defined Specs for common database patterns:
 - **CommonSpecs**: name, slug, status, email, phone, tenant_id, settings
 
 Usage:
-    from krons.specs.catalog import ContentSpecs, AuditSpecs
+    from krons.core.specs.catalog import ContentSpecs, AuditSpecs
 
     content_specs = ContentSpecs.get_specs(dim=1536)
     audit_specs = AuditSpecs.get_specs(use_uuid=True)
     all_specs = content_specs + audit_specs
 
 For custom Specs, use the factories directly:
-    from krons.specs.factory import create_embedding_spec, create_content_spec
+    from krons.core.specs.factory import create_embedding_spec, create_content_spec
 
     my_embedding = create_embedding_spec("embedding", dim=1536)
     my_content = create_content_spec("payload", content_type=MyModel)

krons/{specs → core/specs}/catalog/_audit.py

@@ -10,8 +10,8 @@ from uuid import UUID
 
 from pydantic import BaseModel, Field
 
-from krons.specs.operable import Operable
-from krons.specs.spec import Spec
+from krons.core.specs.operable import Operable
+from krons.core.specs.spec import Spec
 from krons.utils import now_utc
 
 

krons/{specs → core/specs}/catalog/_common.py

@@ -10,8 +10,8 @@ from uuid import UUID
 
 from pydantic import BaseModel
 
-from krons.specs.operable import Operable
-from krons.specs.spec import Spec
+from krons.core.specs.operable import Operable
+from krons.core.specs.spec import Spec
 
 
 class CommonSpecs(BaseModel):

krons/{specs → core/specs}/catalog/_content.py

@@ -11,10 +11,10 @@ from uuid import UUID, uuid4
 
 from pydantic import BaseModel, Field
 
-from krons.specs.operable import Operable
-from krons.specs.spec import Spec
-from krons.types._sentinel import Unset, UnsetType
-from krons.types.db_types import VectorMeta
+from krons.core.specs.operable import Operable
+from krons.core.specs.spec import Spec
+from krons.core.types._sentinel import Unset, UnsetType
+from krons.core.types.db_types import VectorMeta
 from krons.utils import now_utc
 
 

krons/{specs → core/specs}/catalog/_enforcement.py

@@ -10,9 +10,9 @@ from typing import Any
 
 from pydantic import BaseModel, Field, field_validator
 
-from krons.specs.operable import Operable
-from krons.specs.spec import Spec
-from krons.types.base import Enum
+from krons.core.specs.operable import Operable
+from krons.core.specs.spec import Spec
+from krons.core.types.base import Enum
 from krons.utils import now_utc
 
 __all__ = (

krons/{specs → core/specs}/factory.py

@@ -8,10 +8,10 @@ from __future__ import annotations
 from datetime import datetime
 from uuid import UUID, uuid4
 
-from krons.specs.spec import Spec, not_sentinel
-from krons.types import UnsetType
-from krons.types._sentinel import Unset
-from krons.types.base import is_sentinel
+from krons.core.specs.spec import Spec, not_sentinel
+from krons.core.types import UnsetType
+from krons.core.types._sentinel import Unset
+from krons.core.types.base import is_sentinel
 
 
 def create_datetime_spec(name: str, *, use_default: bool) -> Spec:
@@ -74,7 +74,7 @@ def create_embedding_spec(
             return Spec(list[float], name=name, default_factory=list)
         return Spec(list[float], name=name)
 
-    from krons.specs.adapters.sql_ddl import Vector
+    from krons.core.specs.adapters.sql_ddl import Vector
 
     return Spec(Vector[dim], name=name)
 

krons/{specs → core/specs}/operable.py

@@ -6,8 +6,14 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Self
 
+from krons.core.types._sentinel import (
+    MaybeUnset,
+    Unset,
+    UnsetType,
+    is_unset,
+    not_sentinel,
+)
 from krons.protocols import Allowable, Hashable, implements
-from krons.types._sentinel import MaybeUnset, Unset, UnsetType, is_unset, not_sentinel
 
 from .adapters.factory import AdapterType, get_adapter
 from .protocol import SpecAdapter
@@ -311,4 +317,4 @@ class Operable:
         Returns:
             Dict representation of the instance
         """
-        return self.adapter.dump_instance(instance, self)
+        return self.adapter.dump_instance(instance)

krons/{specs → core/specs}/protocol.py

@@ -24,7 +24,7 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
-from krons.types._sentinel import Unset, UnsetType
+from krons.core.types._sentinel import Unset, UnsetType
 
 if TYPE_CHECKING:
     from .operable import Operable
@@ -126,7 +126,9 @@ class SpecAdapter(ABC, Generic[F]):
         Raises:
             NotImplementedError: If adapter doesn't support instance creation
         """
-        raise NotImplementedError(f"{cls.__name__} does not support instance validation")
+        raise NotImplementedError(
+            f"{cls.__name__} does not support instance validation"
+        )
 
     @classmethod
     def dump_instance(cls, instance: Any, **kwargs) -> dict[str, Any]: