Release 2026.10.01.2: instrumentation imports without the database extras

storage, embeddings and backfill need sqlalchemy[asyncio] (greenlet). The
package __init__ now loads their names on first access and raises an
ImportError naming the extra when they are missing. The middleware finds a
DatabaseSink or EmbeddingSink through sys.modules instead of importing them.
Table prefix, embedding dim, sources and event text keys move to constants.py
so they import on a base install.

CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Calendar Versioning](https://calver.org/) (YYYY.MM.DD).
 
+## [2026.10.01.2] - 2026-10-01
+
+The instrumentation imports on a base install, without the database extras.
+
+### Fixed
+- `import fastmcp_feedback.instrumentation` failed on `pip install
+  fastmcp-feedback` without the `instrumentation` extra: the package imported
+  `storage.py` eagerly, which imports `sqlalchemy.ext.asyncio`, and SQLAlchemy
+  2.1 raises `ImportError` there when `greenlet` is missing. `instrument(app)`
+  with `JsonLinesSink`, `CallbackSink` or `MemorySink`, events, redaction and
+  result classification now need only the base dependencies.
+- `DatabaseSink`, `EmbeddingVector`, `build_metadata`, `Embedder`,
+  `EmbeddingSink`, `EmbeddingText`, `OpenAIEmbedder`, `extract_texts`,
+  `backfill_embeddings` and `backfill_feedback` load on first access. Without
+  the extra, accessing one raises `ImportError` naming the missing package and
+  the extra to install (`[instrumentation]`, or `[instrumentation,embeddings]`
+  for the embedding names), chained to the original error. Every access
+  raises, not only the first, although SQLAlchemy itself reports a missing
+  `greenlet` only once. Import paths are unchanged.
+- The middleware finds a `DatabaseSink` or `EmbeddingSink` among its sinks
+  without importing their modules, so `database_sink`, `embedding_sink`,
+  `capture_recent_calls`, `link_feedback`, `feedback_context`, `events_for`,
+  `similar` and `similar_feedback` return their usual empty results on a base
+  install.
+- `DEFAULT_TABLE_PREFIX`, `DEFAULT_EMBEDDING_DIM`, `EMBEDDING_SOURCES` and
+  `DEFAULT_EVENT_TEXT_KEYS` moved to `instrumentation/constants.py` and import
+  without the extras; `storage` and `embeddings` still export them.
+
 ## [2026.10.01.1] - 2026-10-01
 
 A result that says it succeeded is no longer flagged for its own error string.

README.md

@@ -30,6 +30,20 @@ pip install fastmcp-feedback
 uv add "fastmcp-feedback[postgresql]"
 ```
 
+What each install covers:
+
+| Install | Adds | Covers |
+|---------|------|--------|
+| `fastmcp-feedback` | FastMCP, SQLAlchemy, Pydantic | The feedback tools (sync SQLAlchemy, no greenlet), and `instrument(app)` with `JsonLinesSink`, `CallbackSink` and `MemorySink`, events, redaction and result classification |
+| `fastmcp-feedback[instrumentation]` | `sqlalchemy[asyncio]` (greenlet), `aiosqlite` | `DatabaseSink`, `build_metadata`, call history for linking feedback (`capture_recent_calls` across workers, `link_feedback`, `feedback_context`) |
+| `fastmcp-feedback[instrumentation,embeddings]` | `pgvector` | `EmbeddingSink`, `OpenAIEmbedder`, `similar()`, the backfill helpers; pgvector is only needed on PostgreSQL |
+
+Postgres hosts add `asyncpg` for the async sinks. Without the
+`instrumentation` extra, `from fastmcp_feedback.instrumentation import
+DatabaseSink` raises an `ImportError` that names the missing package and the
+extra to install, and the middleware's database helpers return their empty
+defaults (`[]`, `False`).
+
 ### From Git (Latest Development)
 
 ```bash
@@ -181,8 +195,7 @@ instrument(app, [
 
 `DatabaseSink` needs the `instrumentation` extra
 (`uv add "fastmcp-feedback[instrumentation]"`), plus `asyncpg` for Postgres.
-Install the extra even if you already have SQLAlchemy: SQLAlchemy 2.1 no longer
-pulls in `greenlet` by itself, and its async engine cannot run without it.
+The other sinks work on the base install (see [Installation](#installation)).
 
 ### Using your own database and migrations
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastmcp-feedback"
-version = "2026.10.01.1"  # YYYYMMDD.patch versioning - update for each release
+version = "2026.10.01.2"  # YYYYMMDD.patch versioning - update for each release
 description = "Production-ready feedback collection system for FastMCP servers"
 readme = "README.md"
 license = "MIT"

src/fastmcp_feedback/__init__.py

@@ -44,7 +44,7 @@ Quick Start:
 import logging
 
 # Version information - CalVer YYYY.MM.DD
-__version__ = "2026.10.01.1"
+__version__ = "2026.10.01.2"
 __author__ = "Ryan Malloy"
 __email__ = "ryan@supported.systems"
 

src/fastmcp_feedback/instrumentation/__init__.py

@@ -13,21 +13,21 @@ await mw.similar("render timed out")
 await backfill_embeddings(mw.embedding_sink)  # rows stored before embedding
 """
 
-from .backfill import backfill_embeddings, backfill_feedback
+import importlib
+from typing import TYPE_CHECKING, Any
+
 from .classify import (
     DEFAULT_RESULT_CLASSIFIER,
     ResultClassifier,
     soft_error_classifier,
 )
-from .dispatch import RecordDispatcher
-from .embeddings import (
+from .constants import (
+    DEFAULT_EMBEDDING_DIM,
     DEFAULT_EVENT_TEXT_KEYS,
-    Embedder,
-    EmbeddingSink,
-    EmbeddingText,
-    OpenAIEmbedder,
-    extract_texts,
+    DEFAULT_TABLE_PREFIX,
+    EMBEDDING_SOURCES,
 )
+from .dispatch import RecordDispatcher
 from .events import EventRecord
 from .middleware import MODE_ENV_VAR, MODES, InstrumentationMiddleware, instrument
 from .record import ToolCallRecord
@@ -38,14 +38,75 @@ from .redaction import (
     Redactor,
 )
 from .sinks import CallbackSink, JsonLinesSink, MemorySink, Sink
-from .storage import (
-    DEFAULT_EMBEDDING_DIM,
-    DEFAULT_TABLE_PREFIX,
-    EMBEDDING_SOURCES,
-    DatabaseSink,
-    EmbeddingVector,
-    build_metadata,
-)
+
+if TYPE_CHECKING:
+    from .backfill import backfill_embeddings, backfill_feedback
+    from .embeddings import (
+        Embedder,
+        EmbeddingSink,
+        EmbeddingText,
+        OpenAIEmbedder,
+        extract_texts,
+    )
+    from .storage import DatabaseSink, EmbeddingVector, build_metadata
+
+# Names whose modules need the async database stack (sqlalchemy[asyncio],
+# which brings greenlet). Imported on first access, so instrument() and the
+# plain sinks work on a base install.
+_LAZY = {
+    "DatabaseSink": "storage",
+    "EmbeddingVector": "storage",
+    "build_metadata": "storage",
+    "Embedder": "embeddings",
+    "EmbeddingSink": "embeddings",
+    "EmbeddingText": "embeddings",
+    "OpenAIEmbedder": "embeddings",
+    "extract_texts": "embeddings",
+    "backfill_embeddings": "backfill",
+    "backfill_feedback": "backfill",
+}
+_EXTRA = {
+    "storage": "instrumentation",
+    "embeddings": "instrumentation,embeddings",
+    "backfill": "instrumentation,embeddings",
+}
+
+
+def _missing_module(exc: BaseException) -> str:
+    seen: BaseException | None = exc
+    while seen is not None:
+        if isinstance(seen, ImportError) and seen.name:
+            return seen.name
+        seen = seen.__cause__ or seen.__context__
+    return "a dependency"
+
+
+def __getattr__(name: str) -> Any:
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        # Checked first because SQLAlchemy reports a missing greenlet only on
+        # the first import of its asyncio module; a retry would then succeed
+        # and leave an engine that fails at runtime.
+        importlib.import_module("greenlet")
+        value = getattr(importlib.import_module(f".{module}", __name__), name)
+    except ImportError as exc:
+        extra = _EXTRA[module]
+        missing = _missing_module(exc)
+        raise ImportError(
+            f"fastmcp_feedback.instrumentation.{name} needs the async database "
+            f"stack, and {missing} is not installed. Install it with: "
+            f'uv add "fastmcp-feedback[{extra}]" '
+            f'(or pip install "fastmcp-feedback[{extra}]")'
+        ) from exc
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY))
+
 
 __all__ = [
     "CallbackSink",

src/fastmcp_feedback/instrumentation/constants.py

@@ -0,0 +1,12 @@
+"""Defaults shared by the storage and embedding modules.
+
+Kept apart from them so these import without the async database stack.
+"""
+
+DEFAULT_TABLE_PREFIX = "ffb_"
+DEFAULT_EMBEDDING_DIM = 1024
+# source_type values in {prefix}embeddings. Feedback rows survive pruning.
+EMBEDDING_SOURCES = ("feedback", "call_error", "event", "llm")
+FEEDBACK_SOURCE = "feedback"
+# Attribute keys whose text an EmbeddingSink embeds from events.
+DEFAULT_EVENT_TEXT_KEYS = ("error_excerpt", "error", "message", "reason")

src/fastmcp_feedback/instrumentation/embeddings.py

@@ -20,16 +20,15 @@ from typing import Any, Protocol, runtime_checkable
 
 from sqlalchemy import Float, and_, literal, not_, select, tuple_
 
+from .constants import DEFAULT_EVENT_TEXT_KEYS, EMBEDDING_SOURCES
 from .events import EventRecord
 from .record import ToolCallRecord
 from .redaction import Redactor
 from .sinks import Record
-from .storage import EMBEDDING_SOURCES, EmbeddingVector
+from .storage import EmbeddingVector
 
 logger = logging.getLogger(__name__)
 
-DEFAULT_EVENT_TEXT_KEYS = ("error_excerpt", "error", "message", "reason")
-
 
 @runtime_checkable
 class Embedder(Protocol):

src/fastmcp_feedback/instrumentation/middleware.py

@@ -8,12 +8,13 @@ import json
 import logging
 import os
 import random as _random
+import sys
 import time
 import uuid
 from collections import deque
 from collections.abc import Awaitable, Callable, Iterable, Mapping, Sequence
 from datetime import UTC, datetime, timedelta
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from fastmcp import FastMCP
 from fastmcp.server.middleware import Middleware, MiddlewareContext
@@ -27,7 +28,6 @@ from .correlation import (
     select_calls,
 )
 from .dispatch import RecordDispatcher
-from .embeddings import EmbeddingSink
 from .events import (
     MAX_KEY_CHARS,
     MAX_KIND_CHARS,
@@ -38,7 +38,10 @@ from .events import (
 from .record import ToolCallRecord
 from .redaction import Redactor
 from .sinks import JsonLinesSink, Sink
-from .storage import DatabaseSink
+
+if TYPE_CHECKING:
+    from .embeddings import EmbeddingSink
+    from .storage import DatabaseSink
 
 logger = logging.getLogger(__name__)
 
@@ -237,7 +240,7 @@ class InstrumentationMiddleware(Middleware):
         sinks = list(sinks) if sinks is not None else [JsonLinesSink()]
         for sink in sinks:
             # Embedded text gets this middleware's redaction rules too.
-            if isinstance(sink, EmbeddingSink) and sink.redactor is None:
+            if _is_sink(sink, "embeddings", "EmbeddingSink") and sink.redactor is None:
                 sink.redactor = self.redactor
         self.dispatcher = RecordDispatcher(
             sinks,
@@ -573,11 +576,9 @@ class InstrumentationMiddleware(Middleware):
         return rows[-limit:] if limit > 0 else []
 
     @property
-    def embedding_sink(self) -> EmbeddingSink | None:
+    def embedding_sink(self) -> "EmbeddingSink | None":
         """The first EmbeddingSink among the sinks, if any."""
-        return next(
-            (s for s in self.dispatcher.sinks if isinstance(s, EmbeddingSink)), None
-        )
+        return _first_sink(self.dispatcher.sinks, "embeddings", "EmbeddingSink")
 
     async def similar(
         self,
@@ -644,11 +645,9 @@ class InstrumentationMiddleware(Middleware):
             return []
 
     @property
-    def database_sink(self) -> DatabaseSink | None:
+    def database_sink(self) -> "DatabaseSink | None":
         """The first DatabaseSink among the sinks, if any."""
-        return next(
-            (s for s in self.dispatcher.sinks if isinstance(s, DatabaseSink)), None
-        )
+        return _first_sink(self.dispatcher.sinks, "storage", "DatabaseSink")
 
     async def capture_recent_calls(
         self,
@@ -786,6 +785,21 @@ class InstrumentationMiddleware(Middleware):
         await self.dispatcher.aclose()
 
 
+def _is_sink(sink: Any, module: str, name: str) -> bool:
+    """isinstance against a sink class without importing its module.
+
+    storage and embeddings need the async database stack. When the module was
+    never imported, no instance of its class can exist, so the answer is no.
+    """
+    loaded = sys.modules.get(f"{__package__}.{module}")
+    cls = getattr(loaded, name, None) if loaded is not None else None
+    return cls is not None and isinstance(sink, cls)
+
+
+def _first_sink(sinks: Iterable[Any], module: str, name: str) -> Any:
+    return next((s for s in sinks if _is_sink(s, module, name)), None)
+
+
 def _current_context() -> Any:
     try:
         from fastmcp.server.dependencies import get_context

src/fastmcp_feedback/instrumentation/storage.py

@@ -40,22 +40,21 @@ from sqlalchemy.exc import DBAPIError
 from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
 from sqlalchemy.types import TypeDecorator
 
+from .constants import (
+    DEFAULT_EMBEDDING_DIM,
+    DEFAULT_TABLE_PREFIX,
+    FEEDBACK_SOURCE,
+)
+from .constants import EMBEDDING_SOURCES as EMBEDDING_SOURCES  # re-export
 from .events import MAX_KEY_CHARS, MAX_KIND_CHARS, EventRecord
 from .record import ToolCallRecord
 from .sinks import Record
 
 logger = logging.getLogger(__name__)
 
-DEFAULT_TABLE_PREFIX = "ffb_"
-
 # none_as_null: a missing payload is SQL NULL, so "WHERE args IS NULL" works.
 _JSON = JSON(none_as_null=True).with_variant(JSONB(none_as_null=True), "postgresql")
 
-DEFAULT_EMBEDDING_DIM = 1024
-# source_type values in {prefix}embeddings. Feedback rows survive pruning.
-EMBEDDING_SOURCES = ("feedback", "call_error", "event", "llm")
-FEEDBACK_SOURCE = "feedback"
-
 
 class EmbeddingVector(TypeDecorator):
     """pgvector ``VECTOR(dim)`` on PostgreSQL, a JSON list of floats elsewhere.

tests/fixtures/base_install_worker.py

@@ -0,0 +1,105 @@
+"""Exercise the instrumentation as a base install would, then print JSON.
+
+Run in a fresh interpreter. greenlet and aiosqlite are made unimportable
+before anything else loads, as on ``pip install fastmcp-feedback`` without
+the ``instrumentation`` extra. Argument: a directory for the feedback database.
+"""
+
+import sys
+from importlib.metadata import version
+
+# SQLAlchemy 2.1 refuses to import sqlalchemy.ext.asyncio without greenlet,
+# once: a second import succeeds. 2.0 imports it and fails on first use.
+# On 2.0 the module is blocked too, so both versions fail at import.
+_blocked = ["greenlet", "aiosqlite"]
+if tuple(int(p) for p in version("sqlalchemy").split(".")[:2]) < (2, 1):
+    _blocked.append("sqlalchemy.ext.asyncio")
+for _name in _blocked:
+    sys.modules[_name] = None  # import raises ModuleNotFoundError
+
+import asyncio  # noqa: E402
+import io  # noqa: E402
+import json  # noqa: E402
+from pathlib import Path  # noqa: E402
+
+STORAGE = "fastmcp_feedback.instrumentation.storage"
+EMBEDDINGS = "fastmcp_feedback.instrumentation.embeddings"
+
+
+async def run(db_dir: Path) -> dict:
+    from fastmcp import Client, FastMCP
+
+    import fastmcp_feedback.instrumentation as inst
+    from fastmcp_feedback import add_feedback_tools
+    from fastmcp_feedback.instrumentation import (
+        DEFAULT_TABLE_PREFIX,
+        JsonLinesSink,
+        MemorySink,
+        instrument,
+    )
+
+    out: dict = {"prefix": DEFAULT_TABLE_PREFIX}
+    app = FastMCP("base-install")
+
+    @app.tool
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    memory = MemorySink()
+    lines = io.StringIO()
+    mw = instrument(app, [memory, JsonLinesSink(lines)], mode="full")
+    add_feedback_tools(
+        app, database_url=f"sqlite:///{db_dir / 'fb.db'}", instrumentation=mw
+    )
+
+    async with Client(app) as client:
+        result = await client.call_tool("add", {"a": 2, "b": 3})
+        out["result"] = result.content[0].text
+        fb = await client.call_tool(
+            "submit_feedback",
+            {
+                "request": {
+                    "type": "bug",
+                    "title": "base install",
+                    "description": "submitted without the extra",
+                    "submitter": "worker",
+                }
+            },
+        )
+        out["feedback"] = json.loads(fb.content[0].text)
+
+    mw.record_event("job.done", key="j1", attrs={"n": 1})
+    await mw.flush()
+    out["tools"] = [r.tool for r in memory.records if hasattr(r, "tool")]
+    out["event_kinds"] = [r.kind for r in memory.records if hasattr(r, "kind")]
+    out["jsonl_lines"] = len(lines.getvalue().splitlines())
+    out["capture"] = await mw.capture_recent_calls()
+    out["similar"] = await mw.similar("anything")
+    out["similar_feedback"] = await mw.similar_feedback("bug-1")
+    out["feedback_context"] = await mw.feedback_context("bug-1")
+    out["link_feedback"] = await mw.link_feedback("bug-1", [])
+    out["events_for"] = len(await mw.events_for("j1"))
+    out["database_sink"] = mw.database_sink is None
+    out["embedding_sink"] = mw.embedding_sink is None
+    await mw.aclose()
+
+    errors = {}
+    for name in (
+        "DatabaseSink",
+        "EmbeddingSink",
+        "build_metadata",
+        "backfill_feedback",
+    ):
+        for _attempt in range(2):  # SQLAlchemy only complains the first time
+            try:
+                getattr(inst, name)
+                errors.setdefault(name, []).append(None)
+            except ImportError as exc:
+                errors.setdefault(name, []).append(str(exc))
+    out["errors"] = errors
+    out["loaded"] = sorted(m for m in (STORAGE, EMBEDDINGS) if m in sys.modules)
+    return out
+
+
+if __name__ == "__main__":
+    print(json.dumps(asyncio.run(run(Path(sys.argv[1]))), default=str))

tests/unit/test_base_install.py

@@ -0,0 +1,90 @@
+"""The instrumentation works on a base install, without the database extras.
+
+The worker runs in a fresh interpreter with greenlet and aiosqlite made
+unimportable, which is what ``pip install fastmcp-feedback`` leaves out.
+"""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+WORKER = Path(__file__).parent.parent / "fixtures" / "base_install_worker.py"
+
+
+@pytest.fixture(scope="module")
+def report(tmp_path_factory) -> dict:
+    proc = subprocess.run(
+        [sys.executable, str(WORKER), str(tmp_path_factory.mktemp("base"))],
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    assert proc.returncode == 0, proc.stderr[-4000:]
+    return json.loads(proc.stdout.strip().splitlines()[-1])
+
+
+def test_tool_calls_are_recorded(report):
+    assert report["result"] == "5"
+    assert report["tools"] == ["add", "submit_feedback"]
+    assert report["jsonl_lines"] == 4  # two calls, two events
+
+
+def test_events_are_recorded(report):
+    assert report["event_kinds"] == ["feedback.submitted", "job.done"]
+    assert report["events_for"] == 1
+
+
+def test_feedback_tools_work_alongside(report):
+    assert report["feedback"]["success"] is True
+    assert report["feedback"]["linked_calls"] == 0
+
+
+def test_database_helpers_return_empty_defaults(report):
+    assert report["capture"] == []
+    assert report["similar"] == []
+    assert report["similar_feedback"] == []
+    assert report["feedback_context"] == []
+    assert report["link_feedback"] is False
+    assert report["database_sink"] is True
+    assert report["embedding_sink"] is True
+
+
+def test_constants_import_without_the_extra(report):
+    assert report["prefix"] == "ffb_"
+
+
+def test_storage_modules_stay_unloaded(report):
+    assert report["loaded"] == []
+
+
+@pytest.mark.parametrize(
+    ("name", "extra"),
+    [
+        ("DatabaseSink", "[instrumentation]"),
+        ("build_metadata", "[instrumentation]"),
+        ("EmbeddingSink", "[instrumentation,embeddings]"),
+        ("backfill_feedback", "[instrumentation,embeddings]"),
+    ],
+)
+def test_database_names_explain_the_missing_extra(report, name, extra):
+    # Asked twice: SQLAlchemy reports a missing greenlet only on first import.
+    for message in report["errors"][name]:
+        assert message is not None
+        assert "greenlet" in message
+        assert f'uv add "fastmcp-feedback{extra}"' in message
+
+
+def test_lazy_names_resolve_with_the_extra():
+    import fastmcp_feedback.instrumentation as inst
+    from fastmcp_feedback.instrumentation import DatabaseSink, storage
+
+    assert DatabaseSink is storage.DatabaseSink
+    assert set(inst._LAZY) <= set(inst.__all__)
+    assert set(inst.__all__) <= set(dir(inst))
+    for name in inst.__all__:
+        assert getattr(inst, name) is not None
+    with pytest.raises(AttributeError):
+        _ = inst.not_a_name

uv.lock

@@ -601,7 +601,7 @@ wheels = [
 
 [[package]]
 name = "fastmcp-feedback"
-version = "2026.10.1.1"
+version = "2026.10.1.2"
 source = { editable = "." }
 dependencies = [
     { name = "fastmcp" },