sefia-fastapi 0.1.0__tar.gz

sefia_fastapi-0.1.0/.gitignore

@@ -0,0 +1,175 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+# .python-version
+
+# pipenv
+#Pipfile.lock
+
+# UV
+#uv.lock
+
+# poetry
+#poetry.lock
+#poetry.toml
+
+# pdm
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#pixi.lock
+.pixi
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#.idea/
+
+# Abstra
+.abstra/
+
+# Visual Studio Code
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+/out/
+/.local/

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

sefia_fastapi-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,36 @@
+# 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/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "sefia-fastapi"
+description = "FastAPI (HTTP) building blocks for Sefia applications."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "nueruyu" }]
+requires-python = ">=3.11"
+dependencies = [
+    "sefia>=0.1.0",
+    "fastapi>=0.110",
+]
+dynamic = ["version"]
+keywords = [
+    "fastapi",
+    "sse",
+    "human-in-the-loop",
+    "sefia",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/nueruyu/sefia"
+Repository = "https://github.com/nueruyu/sefia"
+Issues = "https://github.com/nueruyu/sefia/issues"
+Documentation = "https://github.com/nueruyu/sefia/tree/main/docs"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sefia_fastapi"]
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "../.." }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.uv.sources]
+sefia = { workspace = true }
+
+[dependency-groups]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]

sefia_fastapi-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/conftest.py

@@ -0,0 +1,24 @@
+from typing import Any
+
+import pytest
+
+
+class InMemoryKeyValueStore:
+    """A dict-backed KeyValueStore for exercising the input core."""
+
+    def __init__(self):
+        self._data: dict[str, Any] = {}
+
+    async def get(self, key: str, type_hint: type) -> Any | None:
+        return self._data.get(key)
+
+    async def set(self, key: str, value: Any, type_hint: type) -> None:
+        self._data[key] = value
+
+    async def delete(self, key: str) -> None:
+        self._data.pop(key, None)
+
+
+@pytest.fixture
+def kv_store() -> InMemoryKeyValueStore:
+    return InMemoryKeyValueStore()

sefia_fastapi-0.1.0/tests/units/test_events.py

@@ -0,0 +1,102 @@
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime
+
+from sefia.llm.events import LLMTokenReceived
+from sefia_fastapi import SessionEvents, SSEEvent
+
+
+class TestSSEEvent:
+    def test_names_are_the_wire_contract(self):
+        assert SSEEvent.TOKEN == "token"
+        assert SSEEvent.INPUT_REQUIRED == "input_required"
+        assert SSEEvent.OUTPUT == "output"
+        assert SSEEvent.COMPLETED == "completed"
+        assert SSEEvent.EXECUTION_FAILED == "execution_failed"
+
+
+class TestPublish:
+    async def test_publish_without_subscribers_is_a_noop(self):
+        events = SessionEvents()
+
+        await events.publish("s1", "token", "hello")
+
+    async def test_subscriber_receives_published_events(self):
+        events = SessionEvents()
+
+        async with events._subscribe("s1") as queue:
+            await events.publish("s1", "token", "hello")
+
+            event = queue.get_nowait()
+
+        assert event.name == "token"
+        assert event.data == "hello"
+
+    async def test_events_are_scoped_to_their_session(self):
+        events = SessionEvents()
+
+        async with events._subscribe("s1") as queue:
+            await events.publish("other", "token", "hello")
+
+            assert queue.empty()
+
+    async def test_unsubscribed_queue_stops_receiving(self):
+        events = SessionEvents()
+
+        async with events._subscribe("s1") as queue:
+            pass
+        await events.publish("s1", "token", "late")
+
+        assert queue.empty()
+
+
+class TestTokenHandler:
+    async def test_relays_tokens_to_the_session_stream(self):
+        events = SessionEvents()
+        handler = events.token_handler("s1")
+
+        async with events._subscribe("s1") as queue:
+            await handler.handle(LLMTokenReceived(token="hi"))
+
+            event = queue.get_nowait()
+
+        assert event.name == SSEEvent.TOKEN
+        assert event.data == "hi"
+
+
+class TestResponse:
+    async def test_streams_published_events_as_sse(self):
+        events = SessionEvents()
+        response = events.response("s1")
+        assert response.media_type == "text/event-stream"
+
+        stream = response.body_iterator.__aiter__()
+        first_chunk = asyncio.ensure_future(stream.__anext__())
+        # Yield control so the stream subscribes before the publish below.
+        await asyncio.sleep(0)
+
+        await events.publish("s1", "completed", {"session_id": "s1"})
+
+        chunk = await asyncio.wait_for(first_chunk, timeout=1)
+        assert chunk == 'event: completed\ndata: {"session_id": "s1"}\n\n'
+
+    async def test_serializes_dataclass_payloads(self):
+        @dataclass(frozen=True)
+        class Payload:
+            interaction_id: str
+            created_at: datetime
+
+        events = SessionEvents()
+        response = events.response("s1")
+
+        stream = response.body_iterator.__aiter__()
+        first_chunk = asyncio.ensure_future(stream.__anext__())
+        await asyncio.sleep(0)
+
+        payload = Payload("x", datetime(2026, 7, 12, 6, 35, 48))
+        await events.publish("s1", "input_required", {"request": payload})
+
+        chunk = await asyncio.wait_for(first_chunk, timeout=1)
+        assert isinstance(chunk, str)  # narrow str | bytes for the `in` checks
+        assert '"interaction_id": "x"' in chunk
+        assert '"created_at": "2026-07-12T06:35:48"' in chunk

sefia_fastapi-0.1.0/tests/units/test_input.py

@@ -0,0 +1,154 @@
+"""Mirrors the CLI input core tests in ``sefia_typer``.
+
+The two packages implement the same semantics independently; keeping the test
+suites aligned guards against unintentional drift.
+"""
+
+import pytest
+from sefia_fastapi import (
+    AmbiguousInputError,
+    InputChannel,
+    InputRequest,
+    UnknownInputError,
+)
+
+
+@pytest.fixture
+def channel(kv_store):
+    channel = InputChannel()
+    with channel.use_store(kv_store):
+        yield channel
+
+
+class TestBinding:
+    async def test_requires_bound_store(self):
+        channel = InputChannel()
+
+        with pytest.raises(RuntimeError):
+            await channel.pending()
+
+    def test_empty_namespace_raises(self):
+        with pytest.raises(ValueError, match="namespace"):
+            InputChannel(namespace="/")
+
+    async def test_namespace_scopes_persisted_keys(self, kv_store):
+        channel = InputChannel(namespace="custom/input")
+
+        with channel.use_store(kv_store):
+            await channel.record_request("x", "why?")
+            await channel.receive_input("answer", reply_to="x")
+
+        assert "custom/input/pending" in kv_store._data
+        assert kv_store._data["custom/input/input/x"] == "answer"
+        assert "input_channel/pending" not in kv_store._data
+
+
+class TestPending:
+    async def test_empty_by_default(self, channel):
+        assert await channel.pending() == []
+
+    async def test_recorded_request_is_pending(self, channel):
+        await channel.record_request("a", "prompt a?")
+
+        assert await channel.pending() == [
+            InputRequest(interaction_id="a", prompt="prompt a?")
+        ]
+
+    async def test_pending_is_ordered_by_interaction_id(self, channel):
+        await channel.record_request("b", "prompt b?")
+        await channel.record_request("a", "prompt a?")
+
+        pending = await channel.pending()
+
+        assert [request.interaction_id for request in pending] == ["a", "b"]
+
+    async def test_resolved_requests_are_dropped_from_pending(self, channel):
+        await channel.record_request("a", "prompt a?")
+        await channel.record_request("b", "prompt b?")
+
+        await channel.receive_input("resolved", reply_to="a")
+
+        pending = await channel.pending()
+        assert [request.interaction_id for request in pending] == ["b"]
+
+    async def test_complete_request_removes_pending(self, channel):
+        await channel.record_request("x", "why?")
+
+        await channel.complete_request("x")
+
+        assert await channel.pending() == []
+
+
+class TestReceiveInput:
+    async def test_none_input_is_ignored(self, channel):
+        await channel.receive_input(None)
+
+        assert await channel.provide_input("any") is None
+
+    async def test_blank_input_is_ignored(self, channel):
+        await channel.receive_input("   ")
+
+        assert await channel.provide_input("any") is None
+
+    async def test_list_input_is_joined(self, channel):
+        await channel.receive_input(["hello", "world"])
+
+        assert await channel.provide_input("any") == "hello world"
+
+    async def test_input_is_queued_when_nothing_pending(self, channel):
+        await channel.receive_input("hello")
+
+        assert await channel.provide_input("any") == "hello"
+
+    async def test_single_pending_request_is_resolved(self, channel):
+        await channel.record_request("only", "prompt?")
+
+        await channel.receive_input("the input")
+
+        assert await channel.provide_input("only") == "the input"
+
+    async def test_multiple_pending_requires_reply_to(self, channel):
+        await channel.record_request("a", "prompt a?")
+        await channel.record_request("b", "prompt b?")
+
+        with pytest.raises(AmbiguousInputError) as exc_info:
+            await channel.receive_input("ambiguous")
+
+        assert sorted(exc_info.value.interaction_ids) == ["a", "b"]
+
+    async def test_reply_to_targets_specific_request(self, channel):
+        await channel.record_request("a", "prompt a?")
+        await channel.record_request("b", "prompt b?")
+
+        await channel.receive_input("for b", reply_to="b")
+
+        assert await channel.provide_input("b") == "for b"
+
+    async def test_reply_to_unknown_request_raises(self, channel):
+        await channel.record_request("a", "prompt a?")
+
+        with pytest.raises(UnknownInputError) as exc_info:
+            await channel.receive_input("oops", reply_to="missing")
+
+        assert exc_info.value.interaction_id == "missing"
+
+
+class TestProvideInput:
+    async def test_returns_none_when_nothing_available(self, channel):
+        assert await channel.provide_input("x") is None
+
+    async def test_queued_inputs_are_claimed_in_order(self, channel):
+        await channel.receive_input("first")
+        await channel.receive_input("second")
+
+        assert await channel.provide_input("i1") == "first"
+        assert await channel.provide_input("i2") == "second"
+        assert await channel.provide_input("i3") is None
+
+    async def test_does_not_claim_queue_with_other_pending(self, channel):
+        await channel.receive_input("queued")
+        await channel.record_request("other", "other prompt?")
+
+        assert await channel.provide_input("mine") is None
+        # The queued input is left for the pending request.
+        assert await channel.provide_input("other") == "queued"