simple-module-ai 0.0.6__py3-none-any.whl

simple_module_ai-0.0.6.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: simple_module_ai
+Version: 0.0.6
+Summary: AI base module: provider-configurable Pydantic AI service layer, encrypted key storage, admin settings UI
+Project-URL: Repository, https://github.com/antosubash/simple_module_python_modules
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+Keywords: ai,embeddings,llm,pydantic-ai,simple-module
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42.0
+Requires-Dist: pydantic-ai-slim[anthropic,google,openai]<3,>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: simple-module-core<0.1,>=0.0.25
+Requires-Dist: simple-module-db<0.1,>=0.0.25
+Requires-Dist: simple-module-hosting<0.1,>=0.0.25
+Requires-Dist: simple-module-settings<0.1,>=0.0.25
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: simple-module-test<0.1,>=0.0.25; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# simple_module_ai
+
+AI base module for [SimpleModule](https://docs.py.simplemodule.dev) apps: one
+provider-configurable service layer (chat + embeddings) that every other
+module shares, with DB-backed settings, encrypted keys and an admin page.
+
+The module owns **connection** configuration — provider, endpoint, key, model
+name. Consuming modules own **behaviour** — agents, prompts, temperature,
+retries, streaming.
+
+## Install
+
+```bash
+pip install simple_module_ai
+```
+
+Add `simple_module_ai` to your host's dependencies; it is discovered at boot
+via the `simple_module` entry point. There are no tables and no migrations.
+
+## Usage (consuming from another module)
+
+Declare the dependency in your module's `ModuleMeta`:
+
+```python
+meta = ModuleMeta(name="MyModule", depends_on=["Ai"], ...)
+```
+
+Then resolve connections wherever you need them:
+
+```python
+from pydantic_ai import Agent
+from sm_ai.contracts import AiNotConfiguredError, resolve_model, resolve_embedder
+
+agent = Agent(instructions="...", output_type=MySchema)
+result = await agent.run(text, model=resolve_model())
+
+embedder = resolve_embedder()          # raises AiNotConfiguredError until the
+result = await embedder.embed_documents(chunks)  # embedding slot is set up
+```
+
+`resolve_model(model_name=...)` overrides the configured model name for
+same-endpoint multi-model setups. `embedding_dim()` returns the configured
+vector width. All errors subclass `AiError`.
+
+> The import package is `sm_ai`, not `ai` — the bare name belongs to another
+> PyPI project and would collide in hosts that install it.
+
+## Settings
+
+Two slots — chat and embeddings — each with provider (`anthropic`, `openai`,
+`google`, `openai_compatible`), model, base URL and API key. The
+`openai_compatible` provider covers vLLM, Ollama and LM Studio (base URL
+required; a blank key is replaced by a protocol-satisfying placeholder).
+
+Configure at `/ai/` (permission `ai.manage`) or seed via `SM_AI_*` env vars
+(e.g. `SM_AI_CHAT_MODEL`); DB values win over env. API keys are encrypted at
+rest with a key derived from `SM_SECRET_KEY` — rotating that secret means
+re-entering provider keys (the old ciphertexts surface as unreadable). A
+settings save hot-reloads the worker that handled it; other workers pick
+the change up on restart.
+
+## Routes
+
+| Route | Purpose |
+|---|---|
+| `GET /ai/` | admin settings page |
+| `GET`/`PUT /api/ai/settings` | read (secrets masked) / update |
+| `POST /api/ai/test` | probe the chat or embedding slot |
+
+Writes require an `X-CSRF-Token` header bound to the session (the admin page
+sends it automatically; the token is mirrored to the `sm_ai_csrf` cookie).

simple_module_ai-0.0.6.dist-info/RECORD

@@ -0,0 +1,24 @@
+sm_ai/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sm_ai/constants.py,sha256=56-c0qjychrNTdZQUTIsNmJ4fWR0FuilraDGJRN5Okc,2161
+sm_ai/crypto.py,sha256=2hN4Kwrf-zCuOB4FzoyxqaiK0hb4ZW5Zaeh3Z2KnNq0,4238
+sm_ai/deps.py,sha256=GecBSmZvSa5OKc4iIAZ1p8Eow2KtJBcQCyAyH7fERhY,483
+sm_ai/module.py,sha256=8WVZQ4zc5RJ4mDFFij7QxLgGRkjjvi1rZT-A6gawRT8,4105
+sm_ai/resolve.py,sha256=k8VfS5_CJYiVVRHVMbjj-D58VZIs1iB8yw5KnuLqa7g,5272
+sm_ai/security.py,sha256=5DQecl-MhR0g1LrM6fK-4eI7IT1nJjuqBC63-mq78MI,5517
+sm_ai/service.py,sha256=n0DVmclGhY9CefIbv53naN4MHHfeSTAC_Sj3rhIAyu4,3428
+sm_ai/services.py,sha256=gO-epH-3w7wRsHEH94LnvIOJgwu2jw764ao7bAoYyW8,1501
+sm_ai/settings.py,sha256=nxO7tdes3Lp5vVtcHTAI-6rvVOU_a6wvmBrxzd0jqDA,1646
+sm_ai/components/SlotCard.tsx,sha256=BOK9pUhV1JqDLY1OPDYTO_HNXUmssBZ9YsfgKIto9bQ,5923
+sm_ai/contracts/__init__.py,sha256=JIZO7Zak7QUwytvz1AQrgHKfERpMTuFlLZAbiZzvHhc,1559
+sm_ai/contracts/errors.py,sha256=cNNeIF_VRGpkjIJiTdoV7jSTulticq8xc1zSe25mPVc,966
+sm_ai/contracts/schemas.py,sha256=r24Nw6TIt2qRPZUEbVXp9Y7OTyD1T3X2lmVZQgLcE10,4220
+sm_ai/endpoints/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sm_ai/endpoints/api.py,sha256=FxcaKgx1uGYPcnFVkfS_xW9XvY2ebMXJad2YRG27NX4,3191
+sm_ai/endpoints/views.py,sha256=OhaS1wSbFeqw-6G6kGWZ3RWEhYthIFmDlhYw3vM3eWY,1006
+sm_ai/pages/Settings.tsx,sha256=x7x8Vg3mmtx51P3zu9V5xbivflpOT19CRd05eB2LhmY,5288
+sm_ai/utils/api.ts,sha256=7ocDHoQ7HchOVL4p9Rjo-C9VzJWhnTGs1Z8ql1iM4Fs,3895
+sm_ai/package.json,sha256=gqIbK95GOiR7d7cVoYv9fU_TQDmuRwymOE3uyDmATYE,391
+simple_module_ai-0.0.6.dist-info/METADATA,sha256=AyS2bojat04XL9inNUG26vqb8BctxuNeArf6M5DluZQ,3600
+simple_module_ai-0.0.6.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+simple_module_ai-0.0.6.dist-info/entry_points.txt,sha256=KOaurGqTntfvV58qnZLWqtotZuJLgIroH6sd2HElOr4,43
+simple_module_ai-0.0.6.dist-info/RECORD,,

simple_module_ai-0.0.6.dist-info/WHEEL

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

simple_module_ai-0.0.6.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[simple_module]
+ai = sm_ai.module:AiModule

sm_ai/components/SlotCard.tsx

@@ -0,0 +1,172 @@
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@simple-module-py/ui/components/ui/card';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import { Label } from '@simple-module-py/ui/components/ui/label';
+
+import type { SlotValues, TestResult } from '../utils/api';
+
+const OPENAI_COMPATIBLE = 'openai_compatible';
+
+export function SlotCard({
+  title,
+  description,
+  idPrefix,
+  providers,
+  optionalSlot,
+  values,
+  hasStoredKey,
+  dirty,
+  busy,
+  testResult,
+  onChange,
+  onTest,
+}: {
+  title: string;
+  description: string;
+  idPrefix: string;
+  providers: string[];
+  /** Embedding-style slot: may be left unconfigured and carries a vector dim. */
+  optionalSlot: boolean;
+  values: SlotValues;
+  hasStoredKey: boolean;
+  /** Unsaved edits present — the probe would test the old saved settings. */
+  dirty: boolean;
+  busy: boolean;
+  testResult: TestResult | null;
+  onChange: (next: SlotValues) => void;
+  onTest: () => void;
+}) {
+  const set = (patch: Partial<SlotValues>) => onChange({ ...values, ...patch });
+  const needsUrl = values.provider === OPENAI_COMPATIBLE;
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{title}</CardTitle>
+        <CardDescription>{description}</CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="space-y-2">
+          <Label htmlFor={`${idPrefix}-provider`}>Provider</Label>
+          <select
+            id={`${idPrefix}-provider`}
+            className="border-input bg-background flex h-9 w-full rounded-md border px-3 py-1 text-sm"
+            value={values.provider}
+            onChange={(e) => set({ provider: e.target.value })}
+            disabled={busy}
+          >
+            {optionalSlot && <option value="">Not configured</option>}
+            {/* An env-seeded value can fall outside the served list; without
+                its own option the select would render unselected while every
+                save 422s with no visible cause. Showing it makes the fix —
+                re-picking a real provider — obvious. */}
+            {values.provider !== '' && !providers.includes(values.provider) && (
+              <option value={values.provider}>{values.provider} (unknown provider)</option>
+            )}
+            {!optionalSlot && values.provider === '' && (
+              <option value="">— pick a provider —</option>
+            )}
+            {providers.map((p) => (
+              <option key={p} value={p}>
+                {p}
+              </option>
+            ))}
+          </select>
+        </div>
+        <div className="space-y-2">
+          <Label htmlFor={`${idPrefix}-model`}>Model</Label>
+          <Input
+            id={`${idPrefix}-model`}
+            value={values.model}
+            onChange={(e) => set({ model: e.target.value })}
+            placeholder="model name, no provider prefix"
+            disabled={busy}
+          />
+        </div>
+        <div className="space-y-2">
+          <Label htmlFor={`${idPrefix}-url`}>
+            Base URL{needsUrl ? ' (required)' : ' (optional override)'}
+          </Label>
+          <Input
+            id={`${idPrefix}-url`}
+            value={values.base_url}
+            onChange={(e) => set({ base_url: e.target.value })}
+            placeholder={needsUrl ? 'http://your-server:8000/v1' : 'provider default'}
+            disabled={busy}
+          />
+        </div>
+        <div className="space-y-2">
+          <Label htmlFor={`${idPrefix}-key`}>API key</Label>
+          <div className="flex gap-2">
+            <Input
+              id={`${idPrefix}-key`}
+              type="password"
+              value={values.api_key}
+              onChange={(e) => set({ api_key: e.target.value, clear_key: false })}
+              placeholder={hasStoredKey ? 'saved — leave blank to keep' : 'not set'}
+              disabled={busy || values.clear_key}
+            />
+            {hasStoredKey && (
+              <Button
+                type="button"
+                variant={values.clear_key ? 'destructive' : 'ghost'}
+                size="sm"
+                disabled={busy}
+                onClick={() => set({ clear_key: !values.clear_key, api_key: '' })}
+              >
+                {values.clear_key ? 'Will clear' : 'Clear'}
+              </Button>
+            )}
+          </div>
+        </div>
+        {optionalSlot && (
+          <div className="space-y-2">
+            <Label htmlFor={`${idPrefix}-dim`}>Vector dimension</Label>
+            <Input
+              id={`${idPrefix}-dim`}
+              type="number"
+              value={values.dim ?? 0}
+              onChange={(e) => set({ dim: Number(e.target.value) || 0 })}
+              disabled={busy}
+            />
+            <p className="text-xs text-muted-foreground">
+              Vector stores fix collection width to this — changing it means re-indexing.
+            </p>
+          </div>
+        )}
+        <div className="flex items-center gap-3">
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            disabled={busy || dirty}
+            onClick={onTest}
+          >
+            Test connection
+          </Button>
+          {dirty && (
+            <span className="text-xs text-muted-foreground">
+              Save your changes first — the test runs against saved settings.
+            </span>
+          )}
+          {!dirty && testResult && (
+            <span
+              data-testid={`${idPrefix}-test-result`}
+              className={testResult.ok ? 'text-sm text-emerald-600' : 'text-sm text-destructive'}
+            >
+              {testResult.ok
+                ? `OK — ${testResult.model} (${testResult.latency_ms} ms)`
+                : testResult.error}
+            </span>
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

sm_ai/constants.py

@@ -0,0 +1,66 @@
+"""AI module constants.
+
+Kept out of the call sites so no module name, route or permission appears as a
+bare literal — see scripts/check_hardcoded_strings.py.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+PACKAGE: Final = "sm_ai"
+MODULE_NAME: Final = "Ai"
+
+ROUTE_PREFIX_API: Final = "/api/ai"
+VIEW_PREFIX: Final = "/ai"
+MENU_URL: Final = f"{VIEW_PREFIX}/"
+MENU_GROUP: Final = "Administration"
+MENU_ICON: Final = "sparkles"
+MENU_ORDER: Final = 116  # just after Branding's 115
+
+# Modules this one depends on (value = that module's ModuleMeta.name).
+_MODULE_SETTINGS: Final = "Settings"
+
+# Inertia page identifier, rendered via this constant at the view (the
+# in-repo check_hardcoded_strings convention; the framework's SM003/SM004
+# literal-pairing convention loses that tie-break — see endpoints/views.py).
+# A unit test pins the value to pages/Settings.tsx.
+_PAGE_SETTINGS: Final = f"{MODULE_NAME}/Settings"
+
+PERM_MANAGE: Final = "ai.manage"
+
+# CSRF channel between the view (mints into the session), the middleware
+# (mirrors to this JS-readable cookie) and the API (verifies this header).
+CSRF_COOKIE: Final = "sm_ai_csrf"
+CSRF_HEADER: Final = "x-csrf-token"
+
+# Provider identifiers (stored values — changing them breaks existing rows).
+PROVIDER_ANTHROPIC: Final = "anthropic"
+PROVIDER_OPENAI: Final = "openai"
+PROVIDER_GOOGLE: Final = "google"
+PROVIDER_OPENAI_COMPATIBLE: Final = "openai_compatible"
+
+CHAT_PROVIDERS: Final = (
+    PROVIDER_ANTHROPIC,
+    PROVIDER_OPENAI,
+    PROVIDER_GOOGLE,
+    PROVIDER_OPENAI_COMPATIBLE,
+)
+# Anthropic offers no embeddings API.
+EMBEDDING_PROVIDERS: Final = (
+    PROVIDER_OPENAI,
+    PROVIDER_GOOGLE,
+    PROVIDER_OPENAI_COMPATIBLE,
+)
+
+# vLLM and friends ignore the key but the OpenAI protocol requires a non-empty
+# value — same literal GeoWiki's AiClientFactory substitutes.
+PLACEHOLDER_API_KEY: Final = "not-needed"
+
+SLOT_CHAT: Final = "chat"
+SLOT_EMBEDDING: Final = "embedding"
+TEST_SLOTS: Final = (SLOT_CHAT, SLOT_EMBEDDING)
+TEST_PROMPT: Final = "Reply with the single word: ok"
+TEST_TIMEOUT_SECONDS: Final = 30
+
+SECRET_FIELDS: Final = frozenset({"chat_api_key", "embedding_api_key"})

sm_ai/contracts/__init__.py

@@ -0,0 +1,54 @@
+"""Public surface for consuming modules.
+
+    from sm_ai.contracts import resolve_model, resolve_embedder, embedding_dim
+
+    agent = Agent(instructions=..., output_type=MySchema)
+    result = await agent.run(text, model=resolve_model())
+
+The base module resolves *connections*; consumers own *behaviour* —
+temperature, prompts, retries and streaming belong on the consumer's Agent.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sm_ai.contracts.errors import AiError, AiKeyUnreadableError, AiNotConfiguredError
+
+if TYPE_CHECKING:
+    from pydantic_ai import Embedder
+    from pydantic_ai.models import Model
+
+
+def resolve_model(model_name: str | None = None) -> Model:
+    """A ready chat model built from the host's AI settings."""
+    from sm_ai import resolve, services
+
+    return resolve.build_chat_model(services.current_settings(), model_name)
+
+
+def resolve_embedder() -> Embedder:
+    """A ready ``Embedder`` built from the host's AI settings."""
+    from sm_ai import resolve, services
+
+    return resolve.build_embedder(services.current_settings())
+
+
+def embedding_dim() -> int:
+    """The configured embedding vector width (vector stores need it)."""
+    from sm_ai import services
+
+    dim = services.current_settings().embedding_dim
+    if dim <= 0:
+        raise AiNotConfiguredError("embedding_dim", "Set the vector width in AI settings.")
+    return dim
+
+
+__all__ = [
+    "AiError",
+    "AiKeyUnreadableError",
+    "AiNotConfiguredError",
+    "embedding_dim",
+    "resolve_embedder",
+    "resolve_model",
+]

sm_ai/contracts/errors.py

@@ -0,0 +1,30 @@
+"""Exceptions consuming modules catch. No imports from the rest of sm_ai —
+this file sits at the bottom of the dependency graph."""
+
+from __future__ import annotations
+
+
+class AiError(Exception):
+    """Base class for AI module errors."""
+
+
+class AiNotConfiguredError(AiError):
+    """A required connection setting is missing or invalid."""
+
+    def __init__(self, field: str, hint: str = "") -> None:
+        self.field = field
+        message = f"AI is not configured: {field!r} is missing or invalid."
+        if hint:
+            message = f"{message} {hint}"
+        super().__init__(message)
+
+
+class AiKeyUnreadableError(AiError):
+    """A stored key has the enc:v1: prefix but cannot be decrypted."""
+
+    def __init__(self, field: str) -> None:
+        self.field = field
+        super().__init__(
+            f"The stored key {field!r} cannot be decrypted — SM_SECRET_KEY has "
+            "changed. Re-enter the key on the AI settings page."
+        )

sm_ai/contracts/schemas.py

@@ -0,0 +1,120 @@
+"""DTOs for the AI settings API. Secrets never travel outward — reads carry
+``has_*_api_key`` booleans; writes treat blank as "keep" and ``clear_*`` as
+explicit removal."""
+
+from __future__ import annotations
+
+from pydantic import field_validator
+from sqlmodel import SQLModel
+
+from sm_ai import constants
+
+
+class AiSettingsOut(SQLModel):
+    """Current AI settings with secrets reduced to presence flags.
+
+    Carries the allowed provider ids so the settings page renders its
+    dropdowns from the same tuples the validators enforce — the frontend
+    holds no provider list of its own.
+    """
+
+    chat_providers: list[str] = list(constants.CHAT_PROVIDERS)
+    embedding_providers: list[str] = list(constants.EMBEDDING_PROVIDERS)
+    chat_provider: str
+    chat_model: str
+    chat_base_url: str
+    has_chat_api_key: bool
+    embedding_provider: str
+    embedding_model: str
+    embedding_base_url: str
+    has_embedding_api_key: bool
+    embedding_dim: int
+
+    @field_validator("chat_provider", "embedding_provider")
+    @classmethod
+    def _normalize_provider(cls, value: str) -> str:
+        # Env-seeded values may be mixed-case ("Anthropic"): resolve.py and
+        # the update validator both accept them via strip().lower(), so the
+        # read path must normalize the same way or the settings dropdown
+        # renders no selection against the lowercase option ids.
+        return value.strip().lower()
+
+
+class AiSettingsUpdate(SQLModel):
+    """Partial update. Key fields: blank/omitted = keep the stored key."""
+
+    chat_provider: str | None = None
+    chat_model: str | None = None
+    chat_base_url: str | None = None
+    chat_api_key: str | None = None
+    clear_chat_api_key: bool = False
+    embedding_provider: str | None = None
+    embedding_model: str | None = None
+    embedding_base_url: str | None = None
+    embedding_api_key: str | None = None
+    clear_embedding_api_key: bool = False
+    embedding_dim: int | None = None
+
+    @field_validator("chat_provider")
+    @classmethod
+    def _chat_provider_known(cls, value: str | None) -> str | None:
+        # Normalize the same way resolve.py reads (strip().lower()): an
+        # env-seeded "Anthropic" works at runtime and must not brick every
+        # save on the settings page until the provider is re-picked.
+        if value is None:
+            return value
+        value = value.strip().lower()
+        if value not in constants.CHAT_PROVIDERS:
+            raise ValueError(f"chat_provider must be one of {constants.CHAT_PROVIDERS}")
+        return value
+
+    @field_validator("embedding_provider")
+    @classmethod
+    def _embedding_provider_known(cls, value: str | None) -> str | None:
+        if value is None:
+            return value
+        value = value.strip().lower()
+        if value != "" and value not in constants.EMBEDDING_PROVIDERS:
+            raise ValueError(
+                f"embedding_provider must be empty or one of {constants.EMBEDDING_PROVIDERS}"
+            )
+        return value
+
+    @field_validator("chat_model")
+    @classmethod
+    def _chat_model_not_blank(cls, value: str | None) -> str | None:
+        # The chat slot is required: without this, a whitespace-only value
+        # strips to "" in build_changes and silently wipes the model, failing
+        # every consumer resolve_model() until an admin re-enters it.
+        if value is not None and not value.strip():
+            raise ValueError("chat_model must not be blank")
+        return value
+
+    @field_validator("embedding_dim")
+    @classmethod
+    def _dim_non_negative(cls, value: int | None) -> int | None:
+        if value is not None and value < 0:
+            raise ValueError("embedding_dim must be >= 0")
+        return value
+
+
+class AiTestRequest(SQLModel):
+    """Which slot to test."""
+
+    slot: str
+
+    @field_validator("slot")
+    @classmethod
+    def _slot_known(cls, value: str) -> str:
+        if value not in constants.TEST_SLOTS:
+            raise ValueError(f"slot must be one of {constants.TEST_SLOTS}")
+        return value
+
+
+class AiTestResult(SQLModel):
+    """Outcome of one test call. Failure is a result, never a 500."""
+
+    ok: bool
+    model: str = ""
+    latency_ms: int = 0
+    error: str = ""

sm_ai/crypto.py

@@ -0,0 +1,114 @@
+"""Fernet encryption for stored provider keys.
+
+The key derives from ``SM_SECRET_KEY`` (SHA-256 → urlsafe base64). The
+running app's secret wins when the module is registered normally — hosts may
+inject ``secret_key`` programmatically via ``create_app(settings=...)``, see
+``set_secret_provider`` — and a private BaseSettings reading the environment
+or the root ``.env`` (the same two sources the host's own BootstrapSettings
+uses) is the fallback. The provider and process env are re-consulted on
+every call (only the ``.env`` file read is cached — it cannot change without
+a restart) and the derived Fernet cached per secret, so an early call
+(before the app's live secret is available) can never pin the fallback
+secret for the process.
+Stored format is ``enc:v1:<fernet token>``:
+
+- prefix present and decrypts        → plaintext key
+- prefix present, decryption fails   → AiKeyUnreadableError (secret key changed)
+- no prefix                          → treated as plaintext, warned once
+  (covers keys pasted through the generic settings UI or seeded from env)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from base64 import urlsafe_b64encode
+from collections.abc import Callable
+from functools import lru_cache
+from hashlib import sha256
+
+from cryptography.fernet import Fernet, InvalidToken
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from sm_ai.contracts.errors import AiKeyUnreadableError
+
+logger = logging.getLogger(__name__)
+
+ENC_PREFIX = "enc:v1:"
+
+# Fields already warned about this process — one line per field is signal,
+# one per read is noise.
+_warned_plaintext: set[str] = set()
+
+
+class _CryptoEnv(BaseSettings):
+    # ``env_file=".env"`` mirrors the host's BootstrapSettings: in the
+    # documented dev flow the secret lives only in the root .env and is never
+    # exported, so reading process env alone would 500 every key save.
+    model_config = SettingsConfigDict(
+        env_prefix="SM_", env_file=".env", extra="ignore"
+    )
+
+    secret_key: str = ""
+
+
+# Installed at module registration: returns the running app's live secret so
+# encryption always matches the app; empty/None falls back to the env read.
+_secret_provider: Callable[[], str] | None = None
+
+
+def set_secret_provider(provider: Callable[[], str]) -> None:
+    """Install the live-secret source."""
+    global _secret_provider
+    _secret_provider = provider
+
+
+def _fernet() -> Fernet:
+    secret = _secret_provider() if _secret_provider is not None else ""
+    # Process env first (free), then the cached .env read: the file cannot
+    # change without a restart, and an uncached BaseSettings would re-open
+    # and re-parse it on every encrypt/decrypt inside async handlers.
+    secret = secret or os.environ.get("SM_SECRET_KEY", "") or _dotenv_secret()
+    if not secret:
+        raise RuntimeError(
+            "SM_SECRET_KEY is not set — the AI module needs it to encrypt "
+            "stored provider keys."
+        )
+    return _fernet_for(secret)
+
+
+@lru_cache(maxsize=1)
+def _dotenv_secret() -> str:
+    return _CryptoEnv().secret_key
+
+
+@lru_cache(maxsize=4)
+def _fernet_for(secret: str) -> Fernet:
+    # Keyed by secret, not cached bare: the provider is consulted per call,
+    # so the first caller racing module registration cannot freeze the
+    # env/.env fallback in for the whole process.
+    return Fernet(urlsafe_b64encode(sha256(secret.encode()).digest()))
+
+
+def encrypt_value(plain: str) -> str:
+    """Encrypt a provider key for storage."""
+    return ENC_PREFIX + _fernet().encrypt(plain.encode()).decode()
+
+
+def decrypt_value(stored: str, field: str) -> str:
+    """Return the plaintext key for a stored value (see module docstring)."""
+    if not stored:
+        return ""
+    if stored.startswith(ENC_PREFIX):
+        try:
+            return _fernet().decrypt(stored[len(ENC_PREFIX) :].encode()).decode()
+        except InvalidToken as exc:
+            raise AiKeyUnreadableError(field) from exc
+    if field not in _warned_plaintext:
+        _warned_plaintext.add(field)
+        logger.warning(
+            "AI setting %r is stored unencrypted; re-save it via the AI "
+            "settings page to encrypt it.",
+            field,
+        )
+    return stored