glyff 0.1.0__py3-none-any.whl

glyff/__init__.py

@@ -0,0 +1,15 @@
+from .decorators import engrave
+from .interfaces import ArgsHasher, Serializer, SessionStore
+from .models import ExecutionId, ExecutionRecord, ExecutionStatus
+from .session import Session
+
+__all__ = [
+    "engrave",
+    "Session",
+    "ExecutionId",
+    "ExecutionRecord",
+    "ExecutionStatus",
+    "ArgsHasher",
+    "Serializer",
+    "SessionStore",
+]

glyff/context.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import contextvars
+from collections.abc import Iterator, Sequence
+from typing import Callable, overload
+
+from .exceptions import ExecutionFailedError, YieldException
+from .interfaces import ArgsHasher, SessionStore, Transaction
+from .models import ExecutionId
+from .sequencer import Sequencer
+
+
+class Context:
+    """Holds the execution context for a workflow session."""
+
+    def __init__(
+        self,
+        session_id: str,
+        store: SessionStore,
+        sequencer: Sequencer,
+        hasher: ArgsHasher,
+        transaction_scope_factory: Callable[[], TransactionScope],
+    ) -> None:
+        self._session_id = session_id
+        self._store = store
+        self._sequencer = sequencer
+        self._hasher = hasher
+        self._transaction_scope_factory = transaction_scope_factory
+        self._tracer = ExecutionTracer()
+        self._current_transaction_scope: TransactionScope | None = None
+
+    @property
+    def store(self) -> SessionStore:
+        return self._store
+
+    @property
+    def sequencer(self) -> Sequencer:
+        return self._sequencer
+
+    @property
+    def hasher(self) -> ArgsHasher:
+        return self._hasher
+
+    @property
+    def tracer(self) -> ExecutionTracer:
+        return self._tracer
+
+    @property
+    def call_stack(self) -> CallStack:
+        return self._tracer.call_stack
+
+    @property
+    def current_execution_id(self) -> ExecutionId | None:
+        return self._tracer.current
+
+    @property
+    def in_transaction(self) -> bool:
+        """Returns True if currently within a transaction scope."""
+        ts = self._current_transaction_scope
+        return ts is not None and ts.in_transaction
+
+    def get_transaction_scope(self) -> TransactionScope:
+        if self._current_transaction_scope is None:
+            self._current_transaction_scope = self._transaction_scope_factory()
+        return self._current_transaction_scope
+
+
+class CallStack(Sequence[ExecutionId]):
+    """Read-only view of the execution call stack. No allocation on access."""
+
+    __slots__ = ("_data",)
+
+    def __init__(self, data: list[ExecutionId]) -> None:
+        self._data = data
+
+    @overload
+    def __getitem__(self, index: int) -> ExecutionId: ...
+    @overload
+    def __getitem__(self, index: slice) -> list[ExecutionId]: ...
+
+    def __getitem__(self, index):
+        return self._data[index]
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __contains__(self, item: object) -> bool:
+        return item in self._data
+
+    def __iter__(self) -> Iterator[ExecutionId]:
+        return iter(self._data)
+
+    def __repr__(self) -> str:
+        return f"CallStack({self._data!r})"
+
+
+class ExecutionTracer:
+    """Records the active call stack during workflow execution."""
+
+    def __init__(self) -> None:
+        self._stack: list[ExecutionId] = []
+        self._view = CallStack(self._stack)
+
+    @property
+    def call_stack(self) -> CallStack:
+        return self._view
+
+    @property
+    def current(self) -> ExecutionId | None:
+        return self._stack[-1] if self._stack else None
+
+    def start(self, execution_id: ExecutionId) -> None:
+        self._stack.append(execution_id)
+
+    def end(self) -> None:
+        self._stack.pop()
+
+
+class TransactionScope:
+    """
+    Manages a transaction across a SessionStore, supporting nesting.
+    The actual commit/rollback only happens at the outermost scope.
+    """
+
+    def __init__(self, store: SessionStore):
+        self._store = store
+        self._level = 0
+        self._transaction: Transaction | None = None
+
+    @property
+    def in_transaction(self) -> bool:
+        """Returns True if currently within a transaction scope."""
+        return self._level > 0
+
+    async def __aenter__(self):
+        if self._level == 0:
+            self._transaction = await self._store.begin_transaction()
+        self._level += 1
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        self._level -= 1
+        if self._level == 0 and self._transaction:
+            if exc_type is None or isinstance(
+                exc_val, (YieldException, ExecutionFailedError)
+            ):
+                # On YieldException or ExecutionFailedError we still commit so that
+                # state (completed subtasks or the failure record) is durably saved.
+                await self._transaction.commit()
+            else:
+                await self._transaction.rollback()
+
+
+_context_var: contextvars.ContextVar[Context] = contextvars.ContextVar("glyff_context")
+
+
+def get_context() -> Context:
+    """Retrieves the current workflow context."""
+    try:
+        return _context_var.get()
+    except LookupError:
+        raise RuntimeError(
+            "Workflow context is not set. Are you running outside a Session?"
+        )
+
+
+def set_context(ctx: Context) -> contextvars.Token:
+    """Sets the current workflow context. Returns a token that can be used to reset it."""
+    return _context_var.set(ctx)
+
+
+def reset_context(token: contextvars.Token) -> None:
+    """Resets the workflow context to a previous state using the provided token."""
+    _context_var.reset(token)

glyff/decorators.py

@@ -0,0 +1,51 @@
+import functools
+import inspect
+from typing import Any, Callable, ParamSpec, TypeVar, cast
+
+from .context import get_context
+from .executor import execute
+from .models import ExecutionId
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def engrave(func: Callable[P, R]) -> Callable[P, R]:
+    """
+    Decorator that makes an async method engraveable and resumable.
+    Its main responsibilities are ExecutionId creation and delegation to the
+    `executor` module.
+    """
+    sig = inspect.signature(func)
+    task_name = getattr(func, "__qualname__", func.__name__)
+
+    try:
+        type_hints = inspect.get_annotations(func, eval_str=True)
+        return_type = type_hints.get("return", Any)
+    except Exception as e:
+        raise TypeError(
+            f"Could not resolve type hints for {task_name}. "
+            f"Please ensure all types are correctly defined and imported. Error: {e}"
+        ) from e
+
+    @functools.wraps(func)
+    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        ctx = get_context()
+        parent_id = ctx.current_execution_id
+        seq = await ctx.sequencer.next(parent_id, task_name)
+        args_hash = ctx.hasher.hash_args(func, sig, args, kwargs)
+        execution_id = ExecutionId(
+            parent_id=parent_id, name=task_name, sequence=seq, args_hash=args_hash
+        )
+
+        result = await execute(
+            ctx=ctx,
+            execution_id=execution_id,
+            func=func,
+            args=args,
+            kwargs=kwargs,
+            return_type=return_type,
+        )
+        return cast(R, result)
+
+    return cast(Callable[P, R], wrapper)

glyff/exceptions.py

@@ -0,0 +1,16 @@
+class YieldException(Exception):
+    """
+    A special exception to signal that the session should be interrupted gracefully.
+    This is not an error, but a signal to stop processing and engrave the state.
+    """
+
+    pass
+
+
+class ExecutionFailedError(Exception):
+    """
+    Raised when attempting to execute a task that has previously failed
+    and its failure state is engraved.
+    """
+
+    pass

glyff/executor.py

@@ -0,0 +1,60 @@
+import traceback
+from typing import Any, Callable
+
+from .context import Context
+from .exceptions import ExecutionFailedError, YieldException
+from .models import ExecutionStatus
+
+
+async def execute(
+    ctx: Context,
+    execution_id: Any,
+    func: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    return_type: type,
+) -> Any:
+    """
+    Orchestrates the execution of a task, including cache checks, transaction
+    management, state recording, and exception handling.
+    """
+    store = ctx.store
+    sequencer = ctx.sequencer
+    tracer = ctx.tracer
+
+    record = await store.get_execution_record(execution_id, return_type)
+
+    if record:
+        if record.status == ExecutionStatus.COMPLETED:
+            return record.result
+        if record.status == ExecutionStatus.FAILED:
+            original_error = Exception(
+                record.error or "Unknown previously failed error"
+            )
+            raise ExecutionFailedError(
+                f"Task {execution_id} failed previously and cannot be re-executed."
+            ) from original_error
+
+    async with ctx.get_transaction_scope():
+        # Reset child sequencers for deterministic re-execution.
+        await sequencer.reset_for_call(execution_id)
+
+        execution = await store.start_execution(execution_id)
+        tracer.start(execution_id)
+
+        try:
+            result = await func(*args, **kwargs)
+            await execution.complete(result, return_type)
+            return result
+        except YieldException:
+            # Interruption is a graceful exit; don't stage failure.
+            # The state remains STARTED, allowing for resumption.
+            raise
+        except Exception as e:
+            error_str = "".join(traceback.format_exception(type(e), e, e.__traceback__))
+            await execution.fail(error_str)
+            raise ExecutionFailedError(
+                f"Task {execution_id} failed: {type(e).__name__}({e})"
+            ) from e
+        finally:
+            tracer.end()

glyff/interfaces.py

@@ -0,0 +1,92 @@
+import inspect
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+from .models import ExecutionId, ExecutionRecord
+
+
+class Transaction(ABC):
+    """
+    A transaction context for a SessionStore.
+    Actual commit/rollback logic is delegated to this object.
+    """
+
+    @abstractmethod
+    async def commit(self) -> None:
+        """Commits the transaction."""
+        ...
+
+    @abstractmethod
+    async def rollback(self) -> None:
+        """Rolls back the transaction."""
+        ...
+
+
+class Execution(ABC):
+    """
+    Represents a single task execution, handling its outcome.
+    """
+
+    @abstractmethod
+    async def complete(self, value: Any, return_type: type) -> None:
+        """Marks the task as successfully completed with a result."""
+        ...
+
+    @abstractmethod
+    async def fail(self, error: str) -> None:
+        """Marks the task as failed with an error message."""
+        ...
+
+
+class Serializer(ABC):
+    """An interface for serializing/deserializing values."""
+
+    @abstractmethod
+    def serialize(self, value: Any, type_hint: type) -> bytes:
+        """Serializes a value to bytes."""
+        ...
+
+    @abstractmethod
+    def deserialize(self, data: bytes, type_hint: type) -> Any:
+        """Deserializes bytes to a value of the given type."""
+        ...
+
+
+class ArgsHasher(ABC):
+    """An interface for creating a deterministic hash from function arguments."""
+
+    @abstractmethod
+    def hash_args(
+        self, func: Callable, sig: inspect.Signature, args: tuple, kwargs: dict
+    ) -> str:
+        """Creates a deterministic hash from a function's arguments."""
+        ...
+
+
+class SessionStore(ABC):
+    """
+    Protocol for a store that persists the state and results of task calls.
+    """
+
+    @abstractmethod
+    async def begin_transaction(self) -> Transaction:
+        """Begins a transaction and returns a transaction object."""
+        ...
+
+    @abstractmethod
+    async def start_execution(self, execution_id: ExecutionId) -> Execution:
+        """
+        Records that a task has started and returns an execution object
+        to manage its outcome.
+        """
+        ...
+
+    @abstractmethod
+    async def get_execution_record(
+        self, execution_id: ExecutionId, return_type: type
+    ) -> ExecutionRecord | None:
+        """
+        Gets the persisted state of a task.
+        The result, if any, is deserialized to the given type.
+        """
+        ...

glyff/models.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ExecutionId:
+    """
+    A unique, deterministic identifier for a task call.
+    It forms a hierarchy through the 'parent_id' attribute.
+    """
+
+    parent_id: ExecutionId | None
+    name: str
+    sequence: int
+    args_hash: str
+
+    def __str__(self) -> str:
+        """
+        Generates a human-readable representation for debugging purposes only.
+        This format is NOT guaranteed to be stable or suitable for use as a persistence key.
+        """
+        parent_info = (
+            f", parent='{self.parent_id.name}#{self.parent_id.sequence}'"
+            if self.parent_id
+            else ""
+        )
+        return f"ExecutionId(name='{self.name}', sequence={self.sequence}{parent_info})"
+
+
+class ExecutionStatus(Enum):
+    """Represents the lifecycle state of a task."""
+
+    STARTED = auto()
+    COMPLETED = auto()
+    FAILED = auto()
+
+
+@dataclass(frozen=True)
+class ExecutionRecord:
+    """Represents the persisted state and outcome of a single execution."""
+
+    status: ExecutionStatus
+    result: Any | None = None
+    error: str | None = None

glyff/sequencer.py

@@ -0,0 +1,40 @@
+import asyncio
+from collections import defaultdict
+
+from .models import ExecutionId
+
+
+class Sequencer:
+    """
+    Generates sequential integers for ExecutionIds in a concurrency-safe manner.
+    Each (parent_id, name) pair has its own independent sequence.
+    """
+
+    def __init__(self):
+        self._locks: dict[tuple[ExecutionId | None, str], asyncio.Lock] = {}
+        self._counters: dict[tuple[ExecutionId | None, str], int] = defaultdict(int)
+        self._meta_lock = asyncio.Lock()
+
+    async def next(self, parent: ExecutionId | None, name: str) -> int:
+        """Returns the next sequence number for the given scope."""
+        key = (parent, name)
+
+        async with self._meta_lock:
+            if key not in self._locks:
+                self._locks[key] = asyncio.Lock()
+
+        async with self._locks[key]:
+            seq = self._counters[key]
+            self._counters[key] += 1
+            return seq
+
+    async def reset_for_call(self, execution_id: ExecutionId) -> None:
+        """
+        Resets all counters that are children of the given ExecutionId.
+        This is crucial for deterministic re-execution of a parent task.
+        """
+        async with self._meta_lock:
+            keys_to_reset = [key for key in self._counters if key[0] == execution_id]
+            for key in keys_to_reset:
+                del self._counters[key]
+                del self._locks[key]

glyff/serialization/__init__.py

@@ -0,0 +1,6 @@
+from .json import JsonArgsHasher, JsonSerializer
+
+__all__ = [
+    "JsonSerializer",
+    "JsonArgsHasher",
+]

glyff/serialization/json.py

@@ -0,0 +1,48 @@
+import hashlib
+import inspect
+import json
+from typing import Any, Callable
+
+from ..interfaces import ArgsHasher, Serializer
+
+
+def _json_stable_dumps(data: Any) -> str:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"))
+
+
+class JsonSerializer(Serializer):
+    """A serializer using only the standard `json` module."""
+
+    def serialize(self, value: Any, type_hint: type) -> bytes:
+        return _json_stable_dumps(value).encode("utf-8")
+
+    def deserialize(self, data: bytes, type_hint: type) -> Any:
+        return json.loads(data.decode("utf-8"))
+
+
+class JsonArgsHasher(ArgsHasher):
+    """An ArgsHasher using standard JSON serialization."""
+
+    def hash_args(
+        self, func: Callable, sig: inspect.Signature, args: tuple, kwargs: dict
+    ) -> str:
+        bound = sig.bind(*args, **kwargs)
+        bound.apply_defaults()
+        args_dict = {
+            name: value
+            for name, value in bound.arguments.items()
+            if sig.parameters[name].kind
+            not in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
+            and name not in ("self", "cls")
+        }
+        try:
+            stable_repr = _json_stable_dumps(args_dict)
+        except TypeError as e:
+            raise TypeError(
+                f"Arguments to '{func.__name__}' could not be serialized to JSON. "
+                "Ensure all arguments are JSON-serializable. "
+                f"Original error: {e}"
+            ) from e
+        hasher = hashlib.sha256()
+        hasher.update(stable_repr.encode("utf-8"))
+        return hasher.hexdigest()

glyff/session.py

@@ -0,0 +1,52 @@
+from .context import Context, TransactionScope, reset_context, set_context
+from .interfaces import ArgsHasher, SessionStore
+from .sequencer import Sequencer
+
+
+class Session:
+    """
+    Manages the lifecycle of a workflow execution.
+    It sets up the execution context and the top-level transaction.
+    """
+
+    def __init__(
+        self,
+        id: str,
+        store: SessionStore,
+        hasher: ArgsHasher,
+    ):
+        self._id = id
+        self._store = store
+        self._hasher = hasher
+        self._context: Context | None = None
+        self._context_token = None
+
+    @property
+    def id(self) -> str:
+        """Returns the ID of this Session."""
+        return self._id
+
+    @property
+    def store(self) -> SessionStore:
+        """Returns the SessionStore used by this Session."""
+        return self._store
+
+    async def __aenter__(self) -> "Session":
+        self._context = Context(
+            session_id=self._id,
+            store=self._store,
+            sequencer=Sequencer(),
+            hasher=self._hasher,
+            transaction_scope_factory=lambda: TransactionScope(self._store),
+        )
+        self._context_token = set_context(self._context)
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self._context and self._context_token:
+            # The top-level transaction is managed by the TransactionScope
+            # obtained via get_transaction_scope(). We just need to ensure
+            # its __aexit__ is called if it was created.
+            if top_level_scope := self._context.get_transaction_scope():
+                await top_level_scope.__aexit__(exc_type, exc_val, exc_tb)
+            reset_context(self._context_token)

glyff/stores/__init__.py

@@ -0,0 +1,7 @@
+from .memory import MemorySessionStore
+from .memory_client import MemoryClient
+
+__all__ = [
+    "MemorySessionStore",
+    "MemoryClient",
+]

glyff/stores/memory.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from ..interfaces import Execution, Serializer, SessionStore, Transaction
+from ..models import ExecutionId, ExecutionRecord, ExecutionStatus
+from .memory_client import MemoryClient
+
+
+class _MemoryTransaction(Transaction):
+    def __init__(self, client: MemoryClient):
+        self._client = client
+
+    async def commit(self) -> None:
+        await self._client.commit_staged()
+
+    async def rollback(self) -> None:
+        self._client.clear_staged()
+
+
+class _MemoryExecution(Execution):
+    def __init__(self, store: MemorySessionStore, execution_id: ExecutionId):
+        self._store = store
+        self._id = execution_id
+
+    def _id_to_key(self, id: ExecutionId, part: str) -> str:
+        return f"execution::{id.name}#{id.sequence}:{id.args_hash}::{part}"
+
+    async def complete(self, value: Any, return_type: type) -> None:
+        self._store._client.stage_write(
+            self._id_to_key(self._id, "status"), ExecutionStatus.COMPLETED
+        )
+        self._store._client.stage_write(
+            self._id_to_key(self._id, "result"),
+            self._store._serializer.serialize(value, return_type),
+        )
+
+    async def fail(self, error: str) -> None:
+        self._store._client.stage_write(
+            self._id_to_key(self._id, "status"), ExecutionStatus.FAILED
+        )
+        self._store._client.stage_write(self._id_to_key(self._id, "error"), error)
+
+
+class MemorySessionStore(SessionStore):
+    """
+    An in-memory implementation of SessionStore for testing and development.
+    This implementation is not persistent across processes.
+    It serializes values to ensure independence, mimicking persisted stores.
+    """
+
+    def __init__(self, client: MemoryClient, serializer: Serializer, **_):
+        self._client = client
+        self._serializer = serializer
+        self._lock = asyncio.Lock()
+
+    def _id_to_key(self, id: ExecutionId, part: str) -> str:
+        return f"execution::{id.name}#{id.sequence}:{id.args_hash}::{part}"
+
+    async def begin_transaction(self) -> Transaction:
+        return _MemoryTransaction(self._client)
+
+    async def start_execution(self, execution_id: ExecutionId) -> Execution:
+        status_key = self._id_to_key(execution_id, "status")
+        if await self._client.read(status_key) is None:
+            self._client.stage_write(status_key, ExecutionStatus.STARTED)
+        return _MemoryExecution(self, execution_id)
+
+    async def get_execution_record(
+        self, execution_id: ExecutionId, return_type: type
+    ) -> ExecutionRecord | None:
+        status: ExecutionStatus | None = await self._client.read(
+            self._id_to_key(execution_id, "status")
+        )
+        if not status:
+            return None
+
+        result = None
+        error = None
+
+        if status == ExecutionStatus.COMPLETED:
+            serialized_value = await self._client.read(
+                self._id_to_key(execution_id, "result")
+            )
+            if serialized_value:
+                result = self._serializer.deserialize(serialized_value, return_type)
+        elif status == ExecutionStatus.FAILED:
+            error = await self._client.read(self._id_to_key(execution_id, "error"))
+
+        return ExecutionRecord(status=status, result=result, error=error)

glyff/stores/memory_client.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+
+class MemoryClient:
+    """A low-level in-memory data store with transactional capabilities."""
+
+    def __init__(self):
+        self._data: dict[str, Any] = {}
+        self._staged_writes: dict[str, Any] = {}
+        self._staged_deletes: set[str] = set()
+        self._lock = asyncio.Lock()
+
+    @property
+    def data(self) -> dict[str, Any]:
+        return self._data
+
+    def clear_staged(self) -> None:
+        self._staged_writes.clear()
+        self._staged_deletes.clear()
+
+    async def commit_staged(self) -> None:
+        async with self._lock:
+            self._data.update(self._staged_writes)
+            for key in self._staged_deletes:
+                self._data.pop(key, None)
+        self.clear_staged()
+
+    async def read(self, key: str) -> Any | None:
+        async with self._lock:
+            return self._data.get(key)
+
+    def stage_write(self, key: str, value: Any) -> None:
+        self._staged_writes[key] = value
+        self._staged_deletes.discard(key)
+
+    def stage_delete(self, key: str) -> None:
+        self._staged_deletes.add(key)
+        self._staged_writes.pop(key, None)

glyff-0.1.0.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: glyff
+Version: 0.1.0
+Summary: Guaranteed Lightweight Yieldable Function Foundation for checkpointed and resumable task execution.
+License: MIT License
+        
+        Copyright (c) 2026 nueruyu
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# glyff
+
+**G**uaranteed **L**ightweight **Y**ieldable **F**unction **F**oundation.
+
+A primitive for pausing async functions across process and request boundaries,
+and resuming them later from the same point.
+
+## Install
+
+```bash
+pip install glyff
+```
+
+`glyff` has no dependencies beyond the Python standard library.
+
+## Behavior
+
+- Marked function calls are recorded in a session-scoped store, keyed by
+  function identity, arguments, and call position.
+- Re-invoking the same call within the same session returns the recorded
+  result instead of re-executing.
+- A call's outcome — success or failure — is permanent once recorded.
+- `YieldException` suspends execution at a function boundary; the session
+  can be resumed later by entering it again with the same session id.
+
+## Public API
+
+| Name              | Description                                                     |
+| ----------------- | --------------------------------------------------------------- |
+| `engrave`         | Decorator that marks an async function for recording.           |
+| `Session`         | Async context manager that scopes a sequence of engraved calls. |
+| `ExecutionId`     | Identifier for a recorded function execution.                   |
+| `ExecutionRecord` | Persisted execution state and result.                           |
+| `ExecutionStatus` | Enum: `STARTED`, `COMPLETED`, `FAILED`.                         |
+| `SessionStore`    | Protocol for storage backends.                                  |
+| `Serializer`      | Protocol for value serialization.                               |
+| `ArgsHasher`      | Protocol for argument hashing.                                  |
+| `YieldException`  | Raised to suspend a session.                                    |
+
+## Extending
+
+- For persistent storage, see [`glyff-file-store`](https://pypi.org/project/glyff-file-store/).
+- For Pydantic-typed serialization, see [`glyff-pydantic`](https://pypi.org/project/glyff-pydantic/).
+- Custom backends can be written by implementing the `SessionStore`,
+  `Serializer`, and `ArgsHasher` protocols.
+
+## Status
+
+Early development. APIs may change before v1.0.
+
+## License
+
+MIT

glyff-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+glyff/__init__.py,sha256=Pe34jmNPe-42wd4F28DlViR1eG3egfmymKUolzmHBiA,354
+glyff/context.py,sha256=zQafkvNDArFzViYNZEOK43VhcdpotfUj5a5qOCx18ww,5160
+glyff/decorators.py,sha256=eOmSKdcmzCwGZ0homEylYXiGmDS1XCsLq5I9gMMFKhc,1609
+glyff/exceptions.py,sha256=a60joZIVHrgaE9Sa9q8bPAzvBfyBOyY3Za2R2CNSYEM,403
+glyff/executor.py,sha256=d2377qaFZlJJgMgezEPWCfcVsb_Jpig8AHOvmikV1gc,2021
+glyff/interfaces.py,sha256=9c7oVYWyc7emVEWkRT7WNoqlFK334apKB6eVAQ7cgtU,2434
+glyff/models.py,sha256=LQxkbYHpzuJtb90SFJ-gknauVMIHo2H4ieVg1L_LiXo,1219
+glyff/sequencer.py,sha256=vruVm6XcAet3oVuI8NubekZ-snRxqW9pZ_3YKIsOc8w,1404
+glyff/session.py,sha256=65i6DRRzGqa-1G-c7kWf4vDgYI_QAvoUTXg8T6I3bMo,1719
+glyff/serialization/__init__.py,sha256=Bm1my_ChfxgzqWvBWWCuAZ9HVQVZk8Lu86dQYGdC3YQ,108
+glyff/serialization/json.py,sha256=HPledSVYhXY9CJp8bWYLgDqDulflwVcBeXemYA34cKI,1585
+glyff/stores/__init__.py,sha256=EMt0UPcq21XfA_f4hC2_ZeTZGmwvGxWWYPk-P5qrBtI,140
+glyff/stores/memory.py,sha256=BPwlCL8IYeudd_Fcy9GTLIk29bYxYChuvjoQ8QEpa3c,3318
+glyff/stores/memory_client.py,sha256=l-80FXLOaagZ3Rya4ePBA60N2topplx3c0xJbk4OYUs,1189
+glyff-0.1.0.dist-info/METADATA,sha256=6HhB9vH6WNp6fpq53TZCZ2CnBxlhK-TIwDMsA_Og8II,4048
+glyff-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+glyff-0.1.0.dist-info/licenses/LICENSE,sha256=bNtLcBZk03HGyB7qD0gK37uO4E0sre_G01X1vCFBPG8,1064
+glyff-0.1.0.dist-info/RECORD,,

glyff-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

glyff-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nueruyu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.