Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

perf(ai): keep Prompture out of the panel's boot path (-24 MB RSS)

Juan Denisb1f002c09d23
diff --git a/backend/app/services/ai_service.py b/backend/app/services/ai_service.py
index 300d79c2..d7636527 100644
--- a/backend/app/services/ai_service.py
+++ b/backend/app/services/ai_service.py
@@ -23,10 +23,25 @@ import dataclasses
import logging
import secrets
import threading
-from typing import Any, Callable, Iterator, Optional
-
-from prompture import Conversation, PIIRedactor, PromptInjectionDetector, ProviderEnvironment
-from prompture.agents.tools_schema import ToolDefinition, ToolRegistry
+from typing import TYPE_CHECKING, Any, Callable, Iterator, Optional
+
+# Prompture is imported lazily, inside the functions that build a Conversation,
+# a ToolRegistry or a ProviderEnvironment — never at module scope.
+#
+# `import prompture` costs ~69 MB of RSS: it pulls ~300 prompture modules plus
+# pydantic, rich, httpx, pygments and jsonschema. This module is reachable from
+# app/api/ai.py, which create_app() registers like every other blueprint, so an
+# eager import made every panel process pay for the assistant at boot whether or
+# not anyone ever opened it — about a third of the panel's idle footprint.
+#
+# `from __future__ import annotations` (above) makes every annotation a string,
+# so the names below are needed only for type checkers and readers, never at
+# runtime. Keep it that way: a new module-level `from prompture import ...`
+# silently puts the 69 MB back. Guarded by
+# backend/tests/test_ai_lazy_import.py.
+if TYPE_CHECKING: # pragma: no cover - typing only
+ from prompture import Conversation, ProviderEnvironment
+ from prompture.agents.tools_schema import ToolRegistry
from app import db
from app.services.ai_tool_registry import ai_tool_registry
@@ -97,9 +112,33 @@ SYSTEM_BASE = (
"result confirms it."
)
-# Guardrail detectors (cheap, regex-based) — instantiate once.
-_injection_detector = PromptInjectionDetector(min_confidence=0.7)
-_pii_redactor = PIIRedactor()
+# Guardrail detectors (cheap, regex-based) — built once, on first use. They are
+# the only Prompture objects the module would otherwise need at import time;
+# constructing them lazily is what keeps `import ai_service` free. Same
+# double-checked pattern as ensure_initialized() below.
+_injection_detector = None
+_pii_redactor = None
+_guardrails_lock = threading.Lock()
+
+
+def _get_injection_detector():
+ global _injection_detector
+ if _injection_detector is None:
+ with _guardrails_lock:
+ if _injection_detector is None:
+ from prompture import PromptInjectionDetector
+ _injection_detector = PromptInjectionDetector(min_confidence=0.7)
+ return _injection_detector
+
+
+def _get_pii_redactor():
+ global _pii_redactor
+ if _pii_redactor is None:
+ with _guardrails_lock:
+ if _pii_redactor is None:
+ from prompture import PIIRedactor
+ _pii_redactor = PIIRedactor()
+ return _pii_redactor
# In-memory registry of live confirmation gates, keyed by conversation id.
# Lives in the single gevent worker (like agent_registry).
@@ -175,6 +214,8 @@ def _decrypted_key() -> Optional[str]:
def build_provider_env(*, provider: Optional[str] = None, api_key: Optional[str] = None,
endpoint: Optional[str] = None) -> ProviderEnvironment:
"""Build a per-instance ProviderEnvironment from stored (or supplied) config."""
+ from prompture import ProviderEnvironment
+
provider = (provider or _setting("ai_provider", "") or "").strip()
if api_key is None:
api_key = _decrypted_key()
@@ -242,7 +283,7 @@ def injection_flagged(text: str) -> bool:
if not _setting("ai_injection_detection", True):
return False
try:
- return bool(_injection_detector.is_injection(text))
+ return bool(_get_injection_detector().is_injection(text))
except Exception:
return False
@@ -255,7 +296,7 @@ def redact_input(text: str) -> str:
if not _pii_enabled():
return text
try:
- return _pii_redactor.redact(text).text
+ return _get_pii_redactor().redact(text).text
except Exception:
return text
@@ -264,7 +305,7 @@ def _maybe_redact_result(result: Any) -> Any:
if not _pii_enabled() or not isinstance(result, str):
return result
try:
- return _pii_redactor.redact(result).text
+ return _get_pii_redactor().redact(result).text
except Exception:
return result
@@ -308,6 +349,8 @@ def build_tool_registry(user, mode: str, gate: Optional["ConfirmationGate"]) ->
descriptors = ai_tool_registry.list_for(user, mode)
if not descriptors:
return None
+ from prompture.agents.tools_schema import ToolDefinition, ToolRegistry
+
reg = ToolRegistry()
for d in descriptors:
fn = _make_write_wrapper(d, user, gate) if d.is_write else _make_read_wrapper(d, user)
@@ -375,6 +418,8 @@ def summarize_action(descriptor, params: dict) -> str:
def build_conversation(row, user, mode: str, page_context: Optional[dict],
gate: Optional["ConfirmationGate"]) -> Conversation:
"""Create a fresh Conversation or resume from the stored export (re-supplying tools)."""
+ from prompture import Conversation
+
registry = build_tool_registry(user, mode, gate)
system = build_system_prompt(user, mode, page_context)
export = row.export
@@ -431,6 +476,8 @@ def derive_title(message: str) -> str:
# In-process invocation (used by plugins via app.plugins_sdk.ai)
# ===========================================================================
def _oneshot_conversation(user, mode: str, page_context: Optional[dict]) -> Conversation:
+ from prompture import Conversation
+
ensure_initialized()
registry = build_tool_registry(user, mode, gate=None)
system = build_system_prompt(user, mode, page_context)
diff --git a/backend/app/services/ai_tool_registry.py b/backend/app/services/ai_tool_registry.py
index cee48226..fd29fd91 100644
--- a/backend/app/services/ai_tool_registry.py
+++ b/backend/app/services/ai_tool_registry.py
@@ -23,7 +23,11 @@ from dataclasses import dataclass, field
from fnmatch import fnmatch
from typing import Any, Callable, Optional
-from prompture.agents.tools_schema import tool_from_function
+# `tool_from_function` is imported inside register() rather than here: this
+# module is reachable at import time from app/api/ai.py and app/plugins_sdk/ai.py,
+# and pulling prompture costs ~69 MB of RSS in every panel process. Registration
+# only happens once someone actually uses the assistant. See ai_service.py's
+# import note and backend/tests/test_ai_lazy_import.py.
logger = logging.getLogger(__name__)
@@ -108,6 +112,8 @@ class AiToolRegistry:
logger.warning("AI tool name too long, truncating: %s", qualified)
qualified = qualified[:MAX_TOOL_NAME_LEN]
# Derive the JSON-Schema parameters + description once, from the real signature.
+ from prompture.agents.tools_schema import tool_from_function
+
td = tool_from_function(func, name=qualified, description=description)
descriptor = ToolDescriptor(
name=name,
diff --git a/backend/tests/test_ai_lazy_import.py b/backend/tests/test_ai_lazy_import.py
new file mode 100644
index 00000000..a9b8b122
--- /dev/null
+++ b/backend/tests/test_ai_lazy_import.py
@@ -0,0 +1,106 @@
+"""Keep Prompture out of the panel's boot path.
+
+The AI assistant is a core primitive, not an extension — ``app/api/ai.py`` is
+registered by ``create_app()`` like every other blueprint. That makes it very
+easy to reintroduce a module-level ``from prompture import ...`` in
+``ai_service`` or ``ai_tool_registry`` without noticing: everything still works,
+the suite still passes, and every panel process silently gains ~25 MB of RSS
+that only servers actually using the assistant should pay for.
+
+``import prompture`` pulls ~300 prompture modules plus rich, pygments, httpx and
+jsonschema. Measured in the production container (gunicorn --workers 1
+--threads 100): 204.9 MB resident with the eager import, 180.5 MB without.
+
+These checks run in a subprocess because the invariant is about a *cold*
+interpreter. By the time pytest reaches this file some other test has usually
+imported prompture already, so an in-process ``sys.modules`` assertion would
+pass no matter what the boot path does.
+"""
+import json
+import os
+import subprocess
+import sys
+
+import pytest
+
+BACKEND_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+# Packages that must not be reachable from a cold `create_app()`. rich and
+# pygments are here because they are the expensive half of prompture's import
+# graph, and a regression usually shows up as all three returning together.
+FORBIDDEN_ROOTS = ("prompture", "rich")
+
+_PROBE = r"""
+import json, sys
+sys.path.insert(0, {backend!r})
+
+import app.services.ai_service # noqa: F401 - the module under guard
+import app.services.ai_tool_registry # noqa: F401
+after_service_import = sorted({{m.split('.')[0] for m in sys.modules}} & set({forbidden!r}))
+
+from app import create_app
+create_app('testing')
+after_create_app = sorted({{m.split('.')[0] for m in sys.modules}} & set({forbidden!r}))
+
+print("RESULT" + json.dumps({{
+ "after_service_import": after_service_import,
+ "after_create_app": after_create_app,
+}}))
+"""
+
+
+def _run_probe():
+ env = dict(os.environ)
+ env.update(
+ DATABASE_URL="sqlite:///:memory:",
+ SECRET_KEY="test",
+ JWT_SECRET_KEY="test",
+ FLASK_ENV="testing",
+ PYTHONDONTWRITEBYTECODE="1",
+ )
+ source = _PROBE.format(backend=BACKEND_DIR, forbidden=list(FORBIDDEN_ROOTS))
+ proc = subprocess.run(
+ [sys.executable, "-c", source],
+ cwd=BACKEND_DIR, env=env, capture_output=True, text=True, timeout=300,
+ )
+ if proc.returncode != 0:
+ pytest.fail(f"probe interpreter failed:\n{proc.stdout}\n{proc.stderr}")
+ for line in proc.stdout.splitlines():
+ if line.startswith("RESULT"):
+ return json.loads(line[len("RESULT"):])
+ pytest.fail(f"probe produced no RESULT line:\n{proc.stdout}\n{proc.stderr}")
+
+
+def test_importing_ai_service_does_not_import_prompture():
+ """`import app.services.ai_service` must stay cheap."""
+ leaked = _run_probe()["after_service_import"]
+ assert leaked == [], (
+ f"Importing the AI service pulled {leaked} at module scope. Move the "
+ "import inside the function that uses it (see the import note at the top "
+ "of app/services/ai_service.py) — a module-level `from prompture import "
+ "...` costs every panel process ~25 MB of RSS at boot."
+ )
+
+
+def test_create_app_does_not_import_prompture():
+ """A booting panel must not pay for the assistant until someone uses it."""
+ leaked = _run_probe()["after_create_app"]
+ assert leaked == [], (
+ f"create_app() pulled {leaked} into the boot path. Something registered "
+ "at startup now imports prompture eagerly — check new AI tool "
+ "registrations, plugins_sdk.ai, and any module-level Prompture type "
+ "annotation that is not under `if TYPE_CHECKING`."
+ )
+
+
+def test_guardrail_detectors_are_built_lazily():
+ """The regex guardrails must not be constructed at import time."""
+ from app.services import ai_service
+
+ # Touching the module must not have built them; only calling the accessor does.
+ assert hasattr(ai_service, "_get_injection_detector")
+ assert hasattr(ai_service, "_get_pii_redactor")
+ detector = ai_service._get_injection_detector()
+ assert detector is not None
+ # Cached: the second call returns the very same instance.
+ assert ai_service._get_injection_detector() is detector