sefia-typer 0.1.0__tar.gz

sefia_typer-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_typer-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_typer-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: sefia-typer
+Version: 0.1.0
+Summary: Typer (CLI) 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: cli,human-in-the-loop,sefia,typer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+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: rich>=13.0
+Requires-Dist: sefia>=0.1.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# sefia-typer
+
+Typer (CLI) building blocks for [Sefia](https://pypi.org/project/sefia/)
+applications.
+
+This package holds the CLI-side pieces that depend only on `sefia` and Typer:
+the input core (an `InputChannel` persisted over a `KeyValueStore`), the
+reporter surface, and the exceptions applications catch. The runtime wiring —
+session management, persistence, and the pausing tool — is provided by an
+integration layer such as `sefios.cli` from
+[`sefios`](https://pypi.org/project/sefios/).
+
+## Install
+
+```bash
+pip install sefia-typer
+```
+
+Most applications install it through the stack instead:
+
+```bash
+pip install 'sefios[cli]'
+```
+
+## 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_typer-0.1.0/README.md

@@ -0,0 +1,36 @@
+# sefia-typer
+
+Typer (CLI) building blocks for [Sefia](https://pypi.org/project/sefia/)
+applications.
+
+This package holds the CLI-side pieces that depend only on `sefia` and Typer:
+the input core (an `InputChannel` persisted over a `KeyValueStore`), the
+reporter surface, and the exceptions applications catch. The runtime wiring —
+session management, persistence, and the pausing tool — is provided by an
+integration layer such as `sefios.cli` from
+[`sefios`](https://pypi.org/project/sefios/).
+
+## Install
+
+```bash
+pip install sefia-typer
+```
+
+Most applications install it through the stack instead:
+
+```bash
+pip install 'sefios[cli]'
+```
+
+## 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_typer-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "sefia-typer"
+description = "Typer (CLI) building blocks for Sefia applications."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "nueruyu" }]
+requires-python = ">=3.11"
+dependencies = [
+    "sefia>=0.1.0",
+    "typer>=0.12",
+    "rich>=13.0",
+]
+dynamic = ["version"]
+keywords = [
+    "cli",
+    "typer",
+    "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",
+    "Environment :: Console",
+    "Framework :: AsyncIO",
+    "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_typer"]
+
+[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", "pytest-mock>=3.12.0"]

sefia_typer-0.1.0/src/sefia_typer/__init__.py

@@ -0,0 +1,36 @@
+"""Typer (CLI) building blocks for Sefia applications.
+
+This package holds the CLI-side pieces that depend only on ``sefia`` and
+Typer: the input core (an :class:`InputChannel` persisted over a
+:class:`KeyValueStore`), the reporter surface, and the exceptions
+applications catch. The runtime wiring — session management, persistence,
+and the pausing tool — is provided by an integration layer such as
+``sefios.cli``.
+"""
+
+from ._input import InputChannel, InputRequest
+from ._kv import KeyValueStore
+from ._reporter import (
+    CLIReporter,
+    DefaultCLIReporter,
+    OutputMessage,
+    ResolvedSession,
+)
+from .exceptions import (
+    AmbiguousInputError,
+    UnknownInputError,
+    UnknownSessionError,
+)
+
+__all__ = [
+    "InputChannel",
+    "InputRequest",
+    "KeyValueStore",
+    "CLIReporter",
+    "DefaultCLIReporter",
+    "OutputMessage",
+    "ResolvedSession",
+    "UnknownSessionError",
+    "UnknownInputError",
+    "AmbiguousInputError",
+]

sefia_typer-0.1.0/src/sefia_typer/_input.py

@@ -0,0 +1,230 @@
+"""The CLI-side input core.
+
+Pending prompts, provided inputs, and queued inputs are persisted through a
+:class:`KeyValueStore`, so a paused CLI invocation 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.
+"""
+
+import inspect
+from collections.abc import Awaitable, Callable
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import TypeVar
+
+from ._kv import KeyValueStore
+from .exceptions import AmbiguousInputError, UnknownInputError
+
+_DEFAULT_NAMESPACE = "input_channel"
+
+T = TypeVar("T")
+MaybeAwaitable = T | Awaitable[T]
+InputRequestHandler = Callable[["InputRequest"], MaybeAwaitable[None]]
+InputPromptDeltaHandler = Callable[[str], MaybeAwaitable[None]]
+
+
+@dataclass(frozen=True)
+class InputRequest:
+    """A pending request for external input."""
+
+    interaction_id: str
+    prompt: str
+
+
+class InputChannel:
+    """The input pipe between a CLI 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. ``on_request`` and ``on_prompt_delta``
+    are the rendering hooks (e.g. a :class:`CLIReporter`).
+
+    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: each task binds and reads its own store.
+    """
+
+    def __init__(
+        self,
+        *,
+        on_request: InputRequestHandler | None = None,
+        on_prompt_delta: InputPromptDeltaHandler | None = None,
+        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
+        )
+        self._on_request = on_request
+        self._on_prompt_delta = on_prompt_delta
+
+    @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 CLI input to a pending request, or queue it for the next one.
+
+        ``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)
+        if self._on_request is not None:
+            await _maybe_await(
+                self._on_request(
+                    InputRequest(interaction_id=interaction_id, prompt=prompt)
+                )
+            )
+
+    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 notify_prompt_delta(self, text: str) -> None:
+        if self._on_prompt_delta is not None:
+            await _maybe_await(self._on_prompt_delta(text))
+
+    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()
+
+
+async def _maybe_await(value: MaybeAwaitable[T]) -> T:
+    if inspect.isawaitable(value):
+        return await value
+    return value

sefia_typer-0.1.0/src/sefia_typer/_kv.py

@@ -0,0 +1,16 @@
+from typing import Any, Protocol
+
+
+class KeyValueStore(Protocol):
+    """Async key-value persistence required by the CLI 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_typer-0.1.0/src/sefia_typer/_reporter.py

@@ -0,0 +1,113 @@
+from dataclasses import dataclass
+from typing import Protocol
+
+import typer
+from sefia.exceptions import InferenceError
+
+from ._input import InputRequest, MaybeAwaitable
+
+
+@dataclass(frozen=True)
+class OutputMessage:
+    """A message the agent emitted to the human without waiting for a reply."""
+
+    interaction_id: str
+    message: str
+
+
+class ResolvedSession(Protocol):
+    """The session-resolution facts a reporter renders.
+
+    Read-only by design: any object with these attributes (such as the
+    integration layer's resolved-session type) satisfies it structurally.
+    """
+
+    @property
+    def session_id(self) -> str: ...
+
+    @property
+    def source(self) -> str: ...
+
+
+class CLIReporter(Protocol):
+    """Receives CLI lifecycle events and renders them for the host application."""
+
+    def on_session_resolved(
+        self,
+        session: ResolvedSession,
+    ) -> MaybeAwaitable[None]: ...
+
+    def on_input_request(
+        self,
+        request: InputRequest,
+    ) -> MaybeAwaitable[None]: ...
+
+    def on_input_prompt_delta(self, text: str) -> MaybeAwaitable[None]: ...
+
+    def on_output(self, message: OutputMessage) -> MaybeAwaitable[None]: ...
+
+    def on_output_message_delta(self, text: str) -> MaybeAwaitable[None]: ...
+
+    def on_interrupted(
+        self,
+        session: ResolvedSession,
+    ) -> MaybeAwaitable[None]: ...
+
+    def on_inference_error(self, error: InferenceError) -> MaybeAwaitable[None]: ...
+
+    def on_session_finished(self) -> MaybeAwaitable[None]: ...
+
+
+class DefaultCLIReporter(CLIReporter):
+    """Default CLI reporter using Typer's standard terminal output helpers."""
+
+    def on_session_resolved(self, session: ResolvedSession) -> None:
+        if session.source == "created":
+            typer.secho(
+                f"> No active session. Starting new session: {session.session_id}",
+                bold=True,
+            )
+        elif session.source == "active":
+            typer.secho(f"> Resuming session {session.session_id}", bold=True)
+
+    def on_input_request(self, request: InputRequest) -> None:
+        typer.echo()
+        typer.secho(
+            f"[INPUT_REQUIRED:{request.interaction_id}]",
+            fg=typer.colors.YELLOW,
+            bold=True,
+            nl=False,
+        )
+        typer.echo(f" {request.prompt}")
+        typer.echo()
+
+    def on_input_prompt_delta(self, text: str) -> None:
+        typer.echo(text, nl=False)
+
+    def on_output(self, message: OutputMessage) -> None:
+        typer.echo()
+        typer.secho(
+            f"[OUTPUT:{message.interaction_id}]",
+            fg=typer.colors.CYAN,
+            bold=True,
+            nl=False,
+        )
+        typer.echo(f" {message.message}")
+        typer.echo()
+
+    def on_output_message_delta(self, text: str) -> None:
+        typer.echo(text, nl=False)
+
+    def on_interrupted(self, session: ResolvedSession) -> None:
+        typer.echo()
+        typer.secho("WAITING FOR INPUT", fg=typer.colors.YELLOW, bold=True)
+        typer.echo("Session interrupted to wait for your input.")
+        typer.echo("To resume, run the script again with your input.")
+
+    def on_inference_error(self, error: InferenceError) -> None:
+        typer.echo()
+        typer.secho("INFERENCE ERROR", fg=typer.colors.RED, bold=True)
+        typer.echo(str(error))
+
+    def on_session_finished(self) -> None:
+        pass

sefia_typer-0.1.0/src/sefia_typer/exceptions.py

@@ -0,0 +1,25 @@
+class UnknownSessionError(Exception):
+    """Raised when a requested CLI 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 a CLI 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

sefia_typer-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_typer-0.1.0/tests/units/test_input.py

@@ -0,0 +1,182 @@
+import pytest
+from sefia_typer import (
+    AmbiguousInputError,
+    InputChannel,
+    InputRequest,
+    UnknownInputError,
+)
+from sefia_typer._input import _to_input_text
+
+
+class TestToInputText:
+    def test_plain_string_is_stripped(self):
+        assert _to_input_text("  hello  ") == "hello"
+
+    def test_list_is_joined_with_spaces(self):
+        assert _to_input_text(["hello", "world"]) == "hello world"
+
+    def test_list_result_is_stripped(self):
+        assert _to_input_text(["  hello  "]) == "hello"
+
+    def test_empty_list_is_empty_string(self):
+        assert _to_input_text([]) == ""
+
+
+@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() == []
+
+    async def test_record_request_notifies(self, kv_store):
+        seen: list[InputRequest] = []
+        channel = InputChannel(on_request=seen.append)
+
+        with channel.use_store(kv_store):
+            await channel.record_request("x", "why?")
+
+        assert seen == [InputRequest(interaction_id="x", prompt="why?")]
+
+    async def test_prompt_delta_notifies(self, kv_store):
+        seen: list[str] = []
+        channel = InputChannel(on_prompt_delta=seen.append)
+
+        with channel.use_store(kv_store):
+            await channel.notify_prompt_delta("What ")
+            await channel.notify_prompt_delta("topic?")
+
+        assert seen == ["What ", "topic?"]
+
+
+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"

sefia_typer-0.1.0/tests/units/test_reporter.py

@@ -0,0 +1,92 @@
+from dataclasses import dataclass
+
+from sefia.exceptions import InvalidInferenceResponseError
+from sefia_typer import DefaultCLIReporter, InputRequest, OutputMessage
+
+
+@dataclass(frozen=True)
+class _StubResolvedSession:
+    session_id: str
+    source: str
+
+
+class TestDefaultCLIReporter:
+    def test_created_session_is_announced(self, capsys):
+        reporter = DefaultCLIReporter()
+
+        reporter.on_session_resolved(
+            _StubResolvedSession(session_id="abc", source="created")
+        )
+
+        assert "abc" in capsys.readouterr().out
+
+    def test_active_session_is_announced(self, capsys):
+        reporter = DefaultCLIReporter()
+
+        reporter.on_session_resolved(
+            _StubResolvedSession(session_id="abc", source="active")
+        )
+
+        assert "abc" in capsys.readouterr().out
+
+    def test_explicit_session_is_quiet(self, capsys):
+        reporter = DefaultCLIReporter()
+
+        reporter.on_session_resolved(
+            _StubResolvedSession(session_id="abc", source="explicit")
+        )
+
+        assert capsys.readouterr().out == ""
+
+    def test_input_request_includes_marker(self, capsys):
+        reporter = DefaultCLIReporter()
+
+        reporter.on_input_request(
+            InputRequest(interaction_id="xyz", prompt="What topic?")
+        )
+
+        output = capsys.readouterr().out
+        assert "INPUT_REQUIRED:xyz" in output
+        assert "What topic?" in output
+
+    def test_input_prompt_delta_is_printed_without_newline(self, capsys):
+        reporter = DefaultCLIReporter()
+
+        reporter.on_input_prompt_delta("What ")
+        reporter.on_input_prompt_delta("topic?")
+
+        assert capsys.readouterr().out == "What topic?"
+
+    def test_output_includes_marker_and_message(self, capsys):
+        reporter = DefaultCLIReporter()
+
+        reporter.on_output(OutputMessage(interaction_id="xyz", message="Hello there!"))
+
+        output = capsys.readouterr().out
+        assert "OUTPUT:xyz" in output
+        assert "Hello there!" in output
+
+    def test_output_message_delta_is_printed_without_newline(self, capsys):
+        reporter = DefaultCLIReporter()
+
+        reporter.on_output_message_delta("Hello ")
+        reporter.on_output_message_delta("there!")
+
+        assert capsys.readouterr().out == "Hello there!"
+
+    def test_interrupted_announces_waiting_state(self, capsys):
+        reporter = DefaultCLIReporter()
+
+        reporter.on_interrupted(_StubResolvedSession(session_id="abc", source="active"))
+
+        assert "WAITING FOR INPUT" in capsys.readouterr().out
+
+    def test_inference_error_is_reported_as_error(self, capsys):
+        reporter = DefaultCLIReporter()
+
+        reporter.on_inference_error(InvalidInferenceResponseError("bad model response"))
+
+        output = capsys.readouterr().out
+        assert "INFERENCE ERROR" in output
+        assert "bad model response" in output
+        assert "WAITING FOR INPUT" not in output