sefia-fastapi 0.1.0__py3-none-any.whl

sefia_fastapi/__init__.py

@@ -0,0 +1,31 @@
+"""FastAPI (HTTP) building blocks for Sefia applications.
+
+This package holds the HTTP-side pieces that depend only on ``sefia`` and
+FastAPI: the input core (an :class:`InputChannel` persisted over a
+:class:`KeyValueStore`), per-session SSE streams (:class:`SessionEvents`),
+and the exceptions an application maps to HTTP responses. The runtime
+wiring — session management, persistence, and the pausing tool — is provided
+by an integration layer such as ``sefios.fastapi``.
+"""
+
+from ._events import SessionEvents, SSEEvent
+from ._input import InputChannel, InputRequest
+from ._kv import KeyValueStore
+from .exceptions import (
+    AmbiguousInputError,
+    InputRequired,
+    UnknownInputError,
+    UnknownSessionError,
+)
+
+__all__ = [
+    "InputChannel",
+    "InputRequest",
+    "KeyValueStore",
+    "SessionEvents",
+    "SSEEvent",
+    "InputRequired",
+    "UnknownSessionError",
+    "UnknownInputError",
+    "AmbiguousInputError",
+]

sefia_fastapi/_events.py

@@ -0,0 +1,102 @@
+"""Per-session server-sent events: publish, token relay, and the SSE response."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi.encoders import jsonable_encoder
+from fastapi.responses import StreamingResponse
+from sefia.event_system import EventHandler
+from sefia.llm.events import LLMTokenReceived
+
+
+class SSEEvent:
+    """The wire names of the server-sent events an application publishes.
+
+    Single source of truth: the facade and browser clients import these rather
+    than repeating literals.
+    """
+
+    TOKEN = "token"
+    INPUT_REQUIRED = "input_required"
+    OUTPUT = "output"
+    COMPLETED = "completed"
+    EXECUTION_FAILED = "execution_failed"
+
+
+@dataclass(frozen=True)
+class _SessionEvent:
+    name: str
+    data: Any
+
+
+class SessionEvents:
+    """Per-session event streams for an HTTP application.
+
+    One object owns the whole surface: :meth:`publish` fans an event out to a
+    session's subscribers, :meth:`token_handler` returns a sefia event handler
+    that relays LLM tokens into the stream, and :meth:`response` serves the
+    stream as a ``text/event-stream`` response. Publishing to a session nobody
+    is subscribed to is a no-op.
+    """
+
+    def __init__(self):
+        self._subscribers: dict[str, set[asyncio.Queue[_SessionEvent]]] = {}
+
+    async def publish(self, session_id: str, name: str, data: Any) -> None:
+        subscribers = list(self._subscribers.get(session_id, ()))
+        if not subscribers:
+            return
+        event = _SessionEvent(name=name, data=data)
+        for queue in subscribers:
+            await queue.put(event)
+
+    def token_handler(self, session_id: str) -> EventHandler[LLMTokenReceived]:
+        """A sefia event handler relaying LLM tokens into this session's stream."""
+        return _TokenRelay(self, session_id)
+
+    def response(self, session_id: str) -> StreamingResponse:
+        """A ``text/event-stream`` response relaying this session's events."""
+        return StreamingResponse(
+            self._event_stream(session_id),
+            media_type="text/event-stream",
+        )
+
+    @asynccontextmanager
+    async def _subscribe(
+        self, session_id: str
+    ) -> AsyncIterator[asyncio.Queue[_SessionEvent]]:
+        queue: asyncio.Queue[_SessionEvent] = asyncio.Queue()
+        subscribers = self._subscribers.setdefault(session_id, set())
+        subscribers.add(queue)
+        try:
+            yield queue
+        finally:
+            subscribers.discard(queue)
+            if not subscribers:
+                self._subscribers.pop(session_id, None)
+
+    async def _event_stream(self, session_id: str) -> AsyncIterator[str]:
+        async with self._subscribe(session_id) as queue:
+            while True:
+                event = await queue.get()
+                yield _format_sse_event(event.name, event.data)
+
+
+class _TokenRelay(EventHandler[LLMTokenReceived]):
+    def __init__(self, events: SessionEvents, session_id: str):
+        self._events = events
+        self._session_id = session_id
+
+    async def handle(self, event: LLMTokenReceived) -> None:
+        await self._events.publish(self._session_id, SSEEvent.TOKEN, event.token)
+
+
+def _format_sse_event(event: str, data: Any) -> str:
+    payload = json.dumps(jsonable_encoder(data), ensure_ascii=False)
+    return f"event: {event}\ndata: {payload}\n\n"

sefia_fastapi/_input.py

@@ -0,0 +1,201 @@
+"""The HTTP-side input core.
+
+Pending prompts, provided inputs, and queued inputs are persisted through a
+:class:`KeyValueStore`, so a paused request can be resumed by a later one. The
+channel only sees primitives; how the runtime provides persistence (and which
+tool raises the pause) is wired up by the integration layer.
+
+Deliberately independent from the CLI counterpart in ``sefia_typer``: the two
+surfaces share semantics today but are free to diverge.
+"""
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+from ._kv import KeyValueStore
+from .exceptions import AmbiguousInputError, UnknownInputError
+
+_DEFAULT_NAMESPACE = "input_channel"
+
+
+@dataclass(frozen=True)
+class InputRequest:
+    """A pending request for external input."""
+
+    interaction_id: str
+    prompt: str
+
+
+class InputChannel:
+    """The input pipe between an HTTP application and a paused agent.
+
+    One object owns the whole lifecycle. The tool-facing side records prompts
+    and picks up provided input (:meth:`record_request` / :meth:`provide_input`
+    / :meth:`complete_request`); the application-facing side routes arriving
+    input to pending requests (:meth:`receive_input`); :meth:`use_store` binds
+    the persistence both sides share.
+
+    Reads observe writes made earlier in the same session because the bound
+    :class:`KeyValueStore` is expected to provide read-your-writes consistency.
+    The active binding is held in a :class:`~contextvars.ContextVar` rather
+    than a plain attribute so that a single shared channel stays correct when
+    several sessions run concurrently (e.g. one asyncio task per HTTP
+    request): each task binds and reads its own store.
+    """
+
+    def __init__(self, *, namespace: str = _DEFAULT_NAMESPACE):
+        namespace = namespace.strip("/")
+        if not namespace:
+            raise ValueError("Input channel namespace must not be empty.")
+        self._namespace = namespace
+        self._active_store: ContextVar[KeyValueStore | None] = ContextVar(
+            "input_active_store", default=None
+        )
+
+    @contextmanager
+    def use_store(self, store: KeyValueStore):
+        """Bind the persistence backing this channel for the enclosed block."""
+        token = self._active_store.set(store)
+        try:
+            yield
+        finally:
+            self._active_store.reset(token)
+
+    async def pending(self) -> list[InputRequest]:
+        """The requests still waiting for input, ordered by interaction id."""
+        pending = await self._pending_map()
+        return [
+            InputRequest(interaction_id=entry["id"], prompt=entry["prompt"])
+            for _, entry in sorted(pending.items())
+        ]
+
+    async def receive_input(
+        self,
+        input_value: str | list[str] | None,
+        *,
+        reply_to: str | None = None,
+    ) -> None:
+        """Route request input to a pending prompt, or queue it for the next.
+
+        ``None`` and blank input are ignored. With ``reply_to`` the input
+        resolves that specific request; otherwise a single pending request is
+        resolved directly, multiple pending requests raise
+        :class:`AmbiguousInputError`, and no pending request queues the input
+        for the next prompt.
+        """
+        if input_value is None:
+            return
+        input_text = _to_input_text(input_value)
+        if not input_text:
+            return
+
+        pending = await self._pending_map()
+
+        if reply_to is not None:
+            if reply_to not in pending:
+                raise UnknownInputError(reply_to)
+            await self._store_input(reply_to, input_text)
+            return
+
+        if len(pending) == 1:
+            await self._store_input(next(iter(pending)), input_text)
+            return
+
+        if len(pending) > 1:
+            raise AmbiguousInputError(sorted(pending))
+
+        await self._queue_input(input_text)
+
+    async def provide_input(self, interaction_id: str) -> str | None:
+        """Return the stored input, or claim a queued one if unambiguous."""
+        provided = await self._stored_input(interaction_id)
+        if provided is not None:
+            return provided
+
+        pending = await self._pending_map()
+        if any(other_id != interaction_id for other_id in pending):
+            return None
+
+        return await self._pop_queued_input()
+
+    async def record_request(self, interaction_id: str, prompt: str) -> None:
+        pending = await self._pending_map()
+        pending[interaction_id] = {"id": interaction_id, "prompt": prompt}
+        await self._save_pending(pending)
+
+    async def complete_request(self, interaction_id: str) -> None:
+        pending = await self._pending_map()
+        pending.pop(interaction_id, None)
+        await self._save_pending(pending)
+
+    async def _pending_map(self) -> dict[str, dict]:
+        store = self._store()
+        pending = await store.get(self._pending_key, dict) or {}
+        if not pending:
+            return {}
+
+        unresolved = {}
+        for interaction_id, request in pending.items():
+            provided = await self._stored_input(interaction_id)
+            if provided is None:
+                unresolved[interaction_id] = request
+
+        await self._save_pending(unresolved)
+        return dict(unresolved)
+
+    async def _save_pending(self, pending: dict[str, dict]) -> None:
+        store = self._store()
+        if pending:
+            await store.set(self._pending_key, pending, dict)
+            return
+
+        await store.delete(self._pending_key)
+
+    async def _stored_input(self, interaction_id: str) -> str | None:
+        return await self._store().get(self._input_key(interaction_id), str)
+
+    async def _store_input(self, interaction_id: str, input_text: str) -> None:
+        await self._store().set(self._input_key(interaction_id), input_text, str)
+
+    async def _queue_input(self, input_text: str) -> None:
+        store = self._store()
+        queue = await store.get(self._queued_key, list) or []
+        queue.append(input_text)
+        await store.set(self._queued_key, queue, list)
+
+    async def _pop_queued_input(self) -> str | None:
+        store = self._store()
+        queue = await store.get(self._queued_key, list)
+        if not queue:
+            return None
+
+        next_input = queue.pop(0)
+        if queue:
+            await store.set(self._queued_key, queue, list)
+        else:
+            await store.delete(self._queued_key)
+        return next_input
+
+    def _store(self) -> KeyValueStore:
+        store = self._active_store.get()
+        if store is None:
+            raise RuntimeError("Input channel is not bound to a store.")
+        return store
+
+    @property
+    def _pending_key(self) -> str:
+        return f"{self._namespace}/pending"
+
+    @property
+    def _queued_key(self) -> str:
+        return f"{self._namespace}/queued"
+
+    def _input_key(self, interaction_id: str) -> str:
+        return f"{self._namespace}/input/{interaction_id}"
+
+
+def _to_input_text(input_value: str | list[str]) -> str:
+    if isinstance(input_value, str):
+        return input_value.strip()
+    return " ".join(input_value).strip()

sefia_fastapi/_kv.py

@@ -0,0 +1,16 @@
+from typing import Any, Protocol
+
+
+class KeyValueStore(Protocol):
+    """Async key-value persistence required by the HTTP input state.
+
+    Structurally matches ``sefios.SessionStorage``, so a bound session storage
+    can be passed in directly; any other implementation with the same shape
+    works too.
+    """
+
+    async def get(self, key: str, type_hint: type) -> Any | None: ...
+
+    async def set(self, key: str, value: Any, type_hint: type) -> None: ...
+
+    async def delete(self, key: str) -> None: ...

sefia_fastapi/exceptions.py

@@ -0,0 +1,39 @@
+from dataclasses import dataclass
+
+
+class UnknownSessionError(Exception):
+    """Raised when a requested HTTP session is not known."""
+
+    def __init__(self, session_id: str):
+        super().__init__(f"Unknown session: {session_id}")
+        self.session_id = session_id
+
+
+class UnknownInputError(Exception):
+    """Raised when an input targets an unknown pending input."""
+
+    def __init__(self, interaction_id: str):
+        super().__init__(f"Unknown pending input: {interaction_id}")
+        self.interaction_id = interaction_id
+
+
+class AmbiguousInputError(Exception):
+    """Raised when multiple pending inputs need an explicit reply target."""
+
+    def __init__(self, interaction_ids: list[str]):
+        super().__init__(
+            "Multiple pending inputs exist. Specify one with reply_to: "
+            + ", ".join(interaction_ids)
+        )
+        self.interaction_ids = interaction_ids
+
+
+@dataclass(frozen=True)
+class InputRequired(Exception):
+    """Raised when a session pauses to wait for external input."""
+
+    interaction_id: str
+    prompt: str
+
+    def __str__(self) -> str:
+        return f"Input required: {self.prompt}"

sefia_fastapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: sefia-fastapi
+Version: 0.1.0
+Summary: FastAPI (HTTP) building blocks for Sefia applications.
+Project-URL: Homepage, https://github.com/nueruyu/sefia
+Project-URL: Repository, https://github.com/nueruyu/sefia
+Project-URL: Issues, https://github.com/nueruyu/sefia/issues
+Project-URL: Documentation, https://github.com/nueruyu/sefia/tree/main/docs
+Author: nueruyu
+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
+Keywords: fastapi,human-in-the-loop,sefia,sse
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: sefia>=0.1.0
+Description-Content-Type: text/markdown
+
+# sefia-fastapi
+
+FastAPI (HTTP) building blocks for [Sefia](https://pypi.org/project/sefia/)
+applications.
+
+This package holds the HTTP-side pieces that depend only on `sefia` and
+FastAPI: the input core (an `InputChannel` persisted over a `KeyValueStore`),
+per-session SSE streams (`SessionEvents`), and the exceptions an application
+maps to HTTP responses. The runtime wiring — session management, persistence,
+and the pausing tool — is provided by an integration layer such as
+`sefios.fastapi` from [`sefios`](https://pypi.org/project/sefios/).
+
+## Install
+
+```bash
+pip install sefia-fastapi
+```
+
+Most applications install it through the stack instead:
+
+```bash
+pip install 'sefios[fastapi]'
+```
+
+## Documentation
+
+See the [repository](https://github.com/nueruyu/sefia) for the full README,
+tutorial, and architecture docs.
+
+## Status
+
+Early development. APIs may change before v1.0.
+
+## License
+
+MIT

sefia_fastapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sefia_fastapi/__init__.py,sha256=eelVE8u2eRvZKgppxnACfsQauyLlNlakTaYBsOzRMpI,939
+sefia_fastapi/_events.py,sha256=uJ5jIryO_fDUFtx6hIWiDqLWbaaeLy_IvmD25dg1b5w,3485
+sefia_fastapi/_input.py,sha256=ZZKZjQM6QNilifZ0hWZUhSnyu5t0USIfGVbJVdcwBFo,7174
+sefia_fastapi/_kv.py,sha256=Zprg6Ag9eo-YS_NnbJh2hODsKYxGDt2zH7ZoeXWMO6A,513
+sefia_fastapi/exceptions.py,sha256=MiCWCIzwgAxw5K8NudDjfHFa7lAXP85fEDPXcWkdcwY,1148
+sefia_fastapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sefia_fastapi-0.1.0.dist-info/METADATA,sha256=1l1gxoK46lbiyEoLG320jNeY15nNAUpXhF_mJjbs-bw,3272
+sefia_fastapi-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+sefia_fastapi-0.1.0.dist-info/licenses/LICENSE,sha256=bNtLcBZk03HGyB7qD0gK37uO4E0sre_G01X1vCFBPG8,1064
+sefia_fastapi-0.1.0.dist-info/RECORD,,

sefia_fastapi-0.1.0.dist-info/WHEEL

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

sefia_fastapi-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.