sefios 0.1.0__py3-none-any.whl

sefios/__init__.py

@@ -0,0 +1,23 @@
+"""Opinionated stack for building applications with the Sefia framework."""
+
+from ._scope import SessionScope
+from ._session_state import get_call_state_store, get_session_storage
+from ._state_store import StateStore
+from .exceptions import NeedsInput
+from .state import StateContainer, StateRegistry, get_state, state
+from .storage import FileSessionStorage, MemorySessionStorage, SessionStorage
+
+__all__ = [
+    "SessionScope",
+    "NeedsInput",
+    "SessionStorage",
+    "StateStore",
+    "MemorySessionStorage",
+    "FileSessionStorage",
+    "get_call_state_store",
+    "get_session_storage",
+    "StateContainer",
+    "StateRegistry",
+    "get_state",
+    "state",
+]

sefios/_scope.py

@@ -0,0 +1,123 @@
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+import glyff
+import glyff_file_store
+import sefia
+from glyff_pydantic import PydanticArgsHasher, PydanticSerializer
+from sefia import HistoryStorage, Profile, Policy
+from sefia.llm import LLMClient
+
+from ._session_state import bind_session_storage
+from .policies import DefaultPolicy
+from .storage import FileSessionStorage, SessionStorage
+
+
+class SessionScope:
+    """
+    Manages shared configuration for Sefia sessions and provides helpers to run
+    code within a configured session context.
+
+    ``session_storage_factory`` is the seam for a custom session-state
+    persistence backend: it receives the session id and returns the
+    :class:`SessionStorage` to bind for that session. By default a
+    :class:`FileSessionStorage` under ``session_dir`` is used.
+
+    ``history_storage`` selects where run history is persisted; defaults to the
+    run's glyff metadata (:class:`~sefia.history_storages.GlyffHistoryStorage`).
+    """
+
+    def __init__(
+        self,
+        *,
+        session_dir: Path,
+        model: str | None = None,
+        llm_client: LLMClient | None = None,
+        policies: list[Policy] | None = None,
+        profiles: list[Profile] | None = None,
+        stream: bool = False,
+        max_steps: int | None = 25,
+        max_repair_attempts: int = 2,
+        session_storage_factory: Callable[[str], SessionStorage] | None = None,
+        history_storage: HistoryStorage | None = None,
+    ):
+        self.session_dir = session_dir
+        self.model = model
+        self.llm_client = llm_client
+        self.policies = list(policies or [])
+        self.profiles = list(profiles or [])
+        self.stream = stream
+        self.max_steps = max_steps
+        self.max_repair_attempts = max_repair_attempts
+        self.session_storage_factory = session_storage_factory
+        self.history_storage = history_storage
+
+    @asynccontextmanager
+    async def session(
+        self,
+        *,
+        session_id: str,
+        model: str | None = None,
+        stream: bool | None = None,
+        policies: list[Policy] | None = None,
+        profiles: list[Profile] | None = None,
+    ) -> AsyncIterator[sefia.Session]:
+        """Run code within a configured Sefia session context."""
+        llm_client = self.llm_client
+        resolved_model = model or self.model
+        resolved_stream = self.stream if stream is None else stream
+
+        if llm_client is None:
+            if resolved_model is None:
+                raise ValueError("Either llm_client or model must be provided.")
+            try:
+                import sefia_litellm
+            except ImportError as e:
+                raise ImportError(
+                    "The 'litellm' extra is required to use the default session "
+                    "setup. Please install it with: pip install 'sefios[litellm]'"
+                ) from e
+            llm_client = sefia_litellm.LiteLLMClient(model=resolved_model)
+
+        serializer = PydanticSerializer()
+
+        backend = glyff_file_store.JsonFileBackend(
+            base_dir=self.session_dir / "glyff_sessions",
+            session_id=session_id,
+        )
+        gs = glyff.Session(
+            id=session_id,
+            backend=backend,
+            serializer=serializer,
+            hasher=PydanticArgsHasher(),
+        )
+        if self.session_storage_factory is not None:
+            session_storage = self.session_storage_factory(session_id)
+        else:
+            session_storage = FileSessionStorage(
+                base_dir=self.session_dir / "sefia_metadata" / session_id,
+                serializer=serializer,
+            )
+
+        final_policies: list[Policy] = list(self.policies)
+        if policies is not None:
+            final_policies.extend(policies)
+        final_policies.append(DefaultPolicy(max_steps=self.max_steps))
+
+        final_profiles: list[Profile] = list(self.profiles)
+        if profiles is not None:
+            final_profiles.extend(profiles)
+
+        async with gs:
+            with bind_session_storage(session_storage):
+                async with sefia.Session(
+                    llm_client=llm_client,
+                    glyff_session=gs,
+                    policies=final_policies,
+                    profiles=final_profiles,
+                    stream=resolved_stream,
+                    history_storage=self.history_storage,
+                    max_repair_attempts=self.max_repair_attempts,
+                ) as session:
+                    yield session

sefios/_session_state.py

@@ -0,0 +1,147 @@
+"""The session-scoped state binding and its accessor functions.
+
+This is the low-level, string-keyed tier of the state API, meant for tool
+implementations: :func:`get_call_state_store` for call-scoped resumable state,
+:func:`get_session_storage` for raw key-value access. Application and handler
+state should normally go through the type-keyed container returned by
+:func:`sefios.get_state` instead.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import hashlib
+import json
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Type, TypeVar
+
+from glyff import ExecutionId
+from glyff import get_context as get_glyff_context
+from glyff.exceptions import ContextNotSetError
+
+from ._state_store import StateStore
+from .storage import SessionStorage
+
+T = TypeVar("T")
+
+
+def _execution_id_to_data(execution_id: ExecutionId) -> dict[str, object]:
+    parent_id = execution_id.parent_id
+    return {
+        "name": execution_id.name,
+        "sequence": execution_id.sequence,
+        "args_hash": execution_id.args_hash,
+        "parent_id": _execution_id_to_data(parent_id) if parent_id else None,
+    }
+
+
+def _execution_id_scope_key(execution_id: ExecutionId) -> str:
+    data = _execution_id_to_data(execution_id)
+    stable_repr = json.dumps(data, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(stable_repr.encode("utf-8")).hexdigest()
+
+
+class _SessionState:
+    """Internal per-session binding over a :class:`SessionStorage`.
+
+    Hands out typed, caching :class:`StateStore` views of the storage — either
+    keyed directly (session scope) or scoped to the current engraved call (call
+    scope). Not exported: callers use the module-level accessor functions.
+    """
+
+    def __init__(self, storage: SessionStorage):
+        self._storage = storage
+        self._state_stores: dict[str, StateStore] = {}
+
+    @property
+    def storage(self) -> SessionStorage:
+        """The underlying :class:`SessionStorage`."""
+        return self._storage
+
+    def get_call_state_store(
+        self, key_suffix: str, state_type: Type[T]
+    ) -> StateStore[T]:
+        try:
+            glyff_ctx = get_glyff_context()
+        except ContextNotSetError:
+            glyff_ctx = None
+        current_execution_id = (
+            glyff_ctx.current_execution_id if glyff_ctx is not None else None
+        )
+
+        if current_execution_id is None:
+            raise RuntimeError(
+                "get_call_state_store can only be used inside an engraved function."
+            )
+
+        scope_key = _execution_id_scope_key(current_execution_id)
+        scoped_key = f"call_state/{scope_key}/{key_suffix}"
+        return self.get_state_store(scoped_key, state_type)
+
+    def get_state_store(self, key: str, state_type: Type[T]) -> StateStore[T]:
+        if key not in self._state_stores:
+            self._state_stores[key] = StateStore(
+                storage=self._storage,
+                key=key,
+                state_type=state_type,
+            )
+        store = self._state_stores[key]
+        if store.state_type != state_type:
+            raise TypeError(
+                f"State store for key '{key}' was already created with a different type."
+            )
+        return store
+
+
+_session_state_var = contextvars.ContextVar[_SessionState]("sefios_session_state")
+
+
+def _get_session_state() -> _SessionState:
+    try:
+        return _session_state_var.get()
+    except LookupError:
+        raise RuntimeError(
+            "No sefios session state is bound. Are you running outside a "
+            "SessionScope.session() (or bind_session_storage) block?"
+        ) from None
+
+
+def get_session_storage() -> SessionStorage:
+    """Returns the :class:`SessionStorage` bound to the current session.
+
+    This is the raw key-value escape hatch for application code that manages
+    its own keys. Raises ``RuntimeError`` if called outside an active session
+    (for example, outside ``SessionScope.session()``).
+    """
+    return _get_session_state().storage
+
+
+def get_call_state_store(key_suffix: str, state_type: Type[T]) -> StateStore[T]:
+    """Returns a :class:`StateStore` scoped to the current engraved call.
+
+    The store's key is derived from the call's execution id, so a resumed
+    invocation that re-enters the same engraved call reads back the same state
+    it stored before pausing. Raises ``RuntimeError`` outside an engraved
+    function or an active session.
+    """
+    return _get_session_state().get_call_state_store(key_suffix, state_type)
+
+
+def get_state_store(key: str, state_type: Type[T]) -> StateStore[T]:
+    """Returns the session-scoped :class:`StateStore` for ``key``.
+
+    Prefer the type-keyed :func:`sefios.get_state` container in application
+    code; this exists for callers that must manage string keys themselves.
+    """
+    return _get_session_state().get_state_store(key, state_type)
+
+
+@contextmanager
+def bind_session_storage(storage: SessionStorage) -> Iterator[None]:
+    """Binds ``storage`` as the current session's state storage."""
+    token = _session_state_var.set(_SessionState(storage))
+    try:
+        yield
+    finally:
+        _session_state_var.reset(token)

sefios/_state_store.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Generic, Type, TypeVar
+
+from .storage import SessionStorage
+
+T = TypeVar("T")
+
+
+class StateStore(Generic[T]):
+    """
+    Provides a type-safe, caching wrapper around a SessionStorage for a specific key and state type.
+    """
+
+    def __init__(self, storage: SessionStorage, key: str, state_type: Type[T]):
+        self._storage = storage
+        self._key = key
+        self._state_type = state_type
+        self._cache: T | None = None
+        self._is_loaded = False
+
+    @property
+    def state_type(self) -> Type[T]:
+        """The state type this store was created for."""
+        return self._state_type
+
+    async def ensure(self) -> T:
+        """
+        Ensures the state is loaded. If it doesn't exist, returns a
+        default-initialized instance. Result is cached for subsequent calls.
+        """
+        if self._is_loaded:
+            if self._cache is None:
+                self._cache = self._state_type()
+            return self._cache
+
+        state = await self._storage.get(self._key, self._state_type)
+        if state is None:
+            state = self._state_type()
+        self._cache = state
+        self._is_loaded = True
+        return state
+
+    async def get(self, default: T | None = None) -> T | None:
+        """
+        Returns the state if it exists, otherwise default (None if not specified).
+        Result is cached for subsequent calls.
+        """
+        if self._is_loaded:
+            return self._cache if self._cache is not None else default
+
+        self._cache = await self._storage.get(self._key, self._state_type)
+        self._is_loaded = True
+        return self._cache if self._cache is not None else default
+
+    async def save(self, state: T) -> None:
+        """Saves the new state and updates the cache."""
+        if not isinstance(state, self._state_type):
+            raise TypeError(f"State must be an instance of {self._state_type.__name__}")
+        await self._storage.set(self._key, state, self._state_type)
+        self._cache = state
+        self._is_loaded = True
+
+    async def delete(self) -> None:
+        """Deletes the state and clears the cache."""
+        await self._storage.delete(self._key)
+        self._cache = None
+        self._is_loaded = True

sefios/cli/__init__.py

@@ -0,0 +1,43 @@
+"""Typer (CLI) integration for the sefios stack.
+
+The facade over the ``sefia_typer`` building blocks: :class:`SefiaCLI` wires
+the CLI input core to sefios' :class:`Input`, session storage,
+and cost accounting. The ``sefia_typer`` surface that applications need
+(reporters and exceptions) is re-exported here, so a single
+``from sefios.cli import ...`` suffices.
+"""
+
+from importlib.util import find_spec
+
+try:
+    from sefia_typer import (
+        AmbiguousInputError,
+        CLIReporter,
+        DefaultCLIReporter,
+        InputRequest,
+        ResolvedSession,
+        UnknownInputError,
+        UnknownSessionError,
+    )
+except ImportError as e:
+    if find_spec("sefia_typer") is None:
+        raise ImportError(
+            "The 'cli' extra is required to use sefios.cli. "
+            "Please install it with: pip install 'sefios[cli]'"
+        ) from e
+    raise
+
+from ._app import CostReportingCLIReporter, SefiaCLI, SefiaCLISession
+
+__all__ = [
+    "SefiaCLI",
+    "SefiaCLISession",
+    "CLIReporter",
+    "DefaultCLIReporter",
+    "CostReportingCLIReporter",
+    "InputRequest",
+    "ResolvedSession",
+    "UnknownSessionError",
+    "UnknownInputError",
+    "AmbiguousInputError",
+]

sefios/cli/_app.py

@@ -0,0 +1,266 @@
+import inspect
+from collections.abc import AsyncIterator, Awaitable
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import TypeVar, cast
+
+import typer
+from sefia import Policy
+from sefia.exceptions import InferenceError, PauseException
+from sefia_typer import (
+    CLIReporter,
+    DefaultCLIReporter,
+    InputChannel,
+)
+from sefia_typer import InputRequest as CLIInputRequest
+from sefia_typer import OutputMessage as CLIOutputMessage
+from sefia_typer import ResolvedSession as CLIResolvedSession
+from sefia_typer import UnknownSessionError as CLIUnknownSessionError
+
+from .._scope import SessionScope
+from .._session_state import get_session_storage
+from ..handlers import CostCalculator, CostState
+from ..sessions import ResolvedSession, SessionManager, UnknownSessionError
+from ..state import get_state
+from ..tools import Input, InputRequest, InputResult, Output, OutputMessage
+
+T = TypeVar("T")
+MaybeAwaitable = T | Awaitable[T]
+_USE_DEFAULT_REPORTER = object()
+
+
+class CostReportingCLIReporter(CLIReporter):
+    """Wraps a reporter to also echo the session's total cost.
+
+    Reads the :class:`CostState` accumulated by the scope's
+    :class:`CostCalculator`, so it only works inside a session run by
+    :class:`SefiaCLI`. This is the default reporter of :class:`SefiaCLI`.
+    """
+
+    def __init__(self, inner: CLIReporter | None = None):
+        self._inner = inner or DefaultCLIReporter()
+
+    def on_session_resolved(self, session: CLIResolvedSession) -> MaybeAwaitable[None]:
+        return self._inner.on_session_resolved(session)
+
+    def on_input_request(self, request: CLIInputRequest) -> MaybeAwaitable[None]:
+        return self._inner.on_input_request(request)
+
+    def on_input_prompt_delta(self, text: str) -> MaybeAwaitable[None]:
+        return self._inner.on_input_prompt_delta(text)
+
+    def on_output(self, message: CLIOutputMessage) -> MaybeAwaitable[None]:
+        return self._inner.on_output(message)
+
+    def on_output_message_delta(self, text: str) -> MaybeAwaitable[None]:
+        return self._inner.on_output_message_delta(text)
+
+    async def on_interrupted(self, session: CLIResolvedSession) -> None:
+        await _maybe_await(self._inner.on_interrupted(session))
+        await self._echo_total_cost()
+
+    async def on_inference_error(self, error: InferenceError) -> None:
+        await _maybe_await(self._inner.on_inference_error(error))
+        await self._echo_total_cost()
+
+    async def on_session_finished(self) -> None:
+        await _maybe_await(self._inner.on_session_finished())
+        await self._echo_total_cost()
+
+    @staticmethod
+    async def _echo_total_cost() -> None:
+        cost_state = await get_state().get(CostState).ensure()
+        typer.echo()
+        typer.secho(f"> Total cost: ${cost_state.cost:.4f}", bold=True)
+
+
+class SefiaCLISession:
+    """Operations available inside a Sefia CLI session context."""
+
+    def __init__(self, *, channel: InputChannel):
+        self._input = channel
+
+    async def accept_input(
+        self,
+        input_value: str | list[str] | None,
+        *,
+        reply_to: str | None = None,
+    ) -> None:
+        """Store CLI input for a pending or upcoming interaction."""
+        await self._input.receive_input(input_value, reply_to=reply_to)
+
+
+class SefiaCLI:
+    """Creates Sefia session contexts for Typer commands.
+
+    The integration facade over the ``sefia_typer`` building blocks: it wires
+    the CLI input core to :class:`Input` and the bound session
+    storage, runs sessions through a :class:`SessionScope` (with cost
+    accounting installed), and maps pauses and inference errors to CLI exit
+    codes.
+    """
+
+    def __init__(
+        self,
+        *,
+        session_dir: Path,
+        reporter: CLIReporter | None | object = _USE_DEFAULT_REPORTER,
+        model: str | None = None,
+        stream: bool = True,
+        max_steps: int | None = 25,
+        policies: list[Policy] | None = None,
+    ):
+        self._reporter = self._resolve_reporter(reporter)
+        self._session_manager = SessionManager(session_dir)
+        self._input = InputChannel(
+            on_request=self._report_input_request,
+            on_prompt_delta=self._report_input_prompt_delta,
+            namespace="cli/input_channel",
+        )
+        self._input_tool = Input(
+            get_input=self._provide_input,
+            on_request=self._record_request,
+            on_complete=self._complete_request,
+            on_prompt_delta=self._input.notify_prompt_delta,
+        )
+        self._output_tool = Output(
+            on_output=self._report_output,
+            on_message_delta=self._report_output_message_delta,
+        )
+
+        scope_policies: list[Policy] = [Policy(handlers=lambda: [CostCalculator()])]
+        if policies is not None:
+            scope_policies.extend(policies)
+        self._session_scope = SessionScope(
+            session_dir=session_dir,
+            model=model,
+            stream=stream,
+            max_steps=max_steps,
+            policies=scope_policies,
+        )
+
+    @property
+    def input_tool(self) -> Input:
+        return self._input_tool
+
+    @property
+    def output_tool(self) -> Output:
+        return self._output_tool
+
+    def create_session(self) -> str:
+        """Create a new active CLI session and return its ID."""
+        return self._session_manager.create_new_active_session()
+
+    def switch_session(self, session_id: str) -> str:
+        """Switch the active CLI session and return its ID."""
+        try:
+            return self._session_manager.switch_active_session(session_id)
+        except UnknownSessionError as e:
+            raise CLIUnknownSessionError(e.session_id) from None
+
+    def get_active_session(self) -> str | None:
+        """Return the active CLI session ID, if any."""
+        return self._session_manager.get_active_session_id()
+
+    @asynccontextmanager
+    async def session(
+        self,
+        *,
+        session_id: str | None = None,
+        model: str | None = None,
+        stream: bool | None = None,
+        policies: list[Policy] | None = None,
+    ) -> AsyncIterator[SefiaCLISession]:
+        """Run code within a resolved Sefia CLI session context."""
+        try:
+            resolved_session = self._session_manager.resolve_session(session_id)
+        except UnknownSessionError as e:
+            raise CLIUnknownSessionError(e.session_id) from None
+
+        try:
+            await self._report_session_resolved(resolved_session)
+            async with self._session_scope.session(
+                session_id=resolved_session.session_id,
+                model=model,
+                stream=stream,
+                policies=policies,
+            ):
+                with self._input.use_store(get_session_storage()):
+                    try:
+                        yield SefiaCLISession(channel=self._input)
+                    except InferenceError as e:
+                        await self._report_inference_error(e)
+                        raise
+                    except PauseException:
+                        # Any pause (NeedsInput, or a future pause type) is a
+                        # graceful interrupt, not a failure. The session context
+                        # is still alive here, so reporters may read running
+                        # state (e.g. cost) via get_state().
+                        await self._report_interrupted(resolved_session)
+                        raise
+                    else:
+                        await self._report_session_finished()
+        except InferenceError:
+            raise typer.Exit(code=1) from None
+        except PauseException:
+            raise typer.Exit(code=0)
+
+    async def _provide_input(self, request: InputRequest) -> str | None:
+        return await self._input.provide_input(request.interaction_id)
+
+    async def _record_request(self, request: InputRequest) -> None:
+        await self._input.record_request(request.interaction_id, request.prompt)
+
+    async def _complete_request(self, result: InputResult) -> None:
+        await self._input.complete_request(result.interaction_id)
+
+    async def _report_session_resolved(self, session: ResolvedSession) -> None:
+        if self._reporter is not None:
+            await _maybe_await(self._reporter.on_session_resolved(session))
+
+    async def _report_input_request(self, request: CLIInputRequest) -> None:
+        if self._reporter is not None:
+            await _maybe_await(self._reporter.on_input_request(request))
+
+    async def _report_input_prompt_delta(self, text: str) -> None:
+        if self._reporter is not None:
+            await _maybe_await(self._reporter.on_input_prompt_delta(text))
+
+    async def _report_output(self, message: OutputMessage) -> None:
+        if self._reporter is not None:
+            await _maybe_await(
+                self._reporter.on_output(
+                    CLIOutputMessage(
+                        interaction_id=message.interaction_id,
+                        message=message.message,
+                    )
+                )
+            )
+
+    async def _report_output_message_delta(self, text: str) -> None:
+        if self._reporter is not None:
+            await _maybe_await(self._reporter.on_output_message_delta(text))
+
+    async def _report_interrupted(self, session: ResolvedSession) -> None:
+        if self._reporter is not None:
+            await _maybe_await(self._reporter.on_interrupted(session))
+
+    async def _report_inference_error(self, error: InferenceError) -> None:
+        if self._reporter is not None:
+            await _maybe_await(self._reporter.on_inference_error(error))
+
+    async def _report_session_finished(self) -> None:
+        if self._reporter is not None:
+            await _maybe_await(self._reporter.on_session_finished())
+
+    @staticmethod
+    def _resolve_reporter(reporter: CLIReporter | None | object) -> CLIReporter | None:
+        if reporter is _USE_DEFAULT_REPORTER:
+            return CostReportingCLIReporter()
+        return cast(CLIReporter | None, reporter)
+
+
+async def _maybe_await(value: MaybeAwaitable[T]) -> T:
+    if inspect.isawaitable(value):
+        return await value
+    return value

sefios/exceptions.py

@@ -0,0 +1,23 @@
+from sefia.exceptions import PauseException
+
+
+class NeedsInput(PauseException):
+    """
+    Raised by an input-awaiting tool to pause the run until input is available.
+
+    Carries the ``prompt`` shown to whoever provides the input, and the
+    ``interaction_id`` identifying the paused request so integration layers
+    can report exactly which request is waiting without re-reading state.
+    Catch it to surface the pause to your caller; once the input is recorded,
+    re-invoking the same session replays the completed steps and re-runs the
+    tool, which now returns the input.
+
+    It subclasses :class:`sefia.exceptions.PauseException`, so the sefia executor
+    propagates it as a pause (never reporting it as a failure) without the core
+    needing to know about external input specifically.
+    """
+
+    def __init__(self, prompt: str, *, interaction_id: str | None = None) -> None:
+        super().__init__(prompt)
+        self.prompt = prompt
+        self.interaction_id = interaction_id