simple-module-ai 0.0.7__tar.gz

simple_module_ai-0.0.7/.gitignore

@@ -0,0 +1,43 @@
+.claude/settings.local.json
+
+# Python
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+
+# Node
+node_modules/
+dist/
+
+# Built module frontend bundles (force-included into wheels at build time)
+modules/*/*/static/dist/
+
+# Host build output and the module-pages manifest regenerated by `make gen-pages`
+host/static/dist/
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+
+# Local databases
+host/*.db
+
+# Runtime upload storage (PagebuilderSettings.media_root)
+var/
+
+# Env
+.env
+
+# Playwright
+playwright-report/
+test-results/
+.playwright-mcp/
+
+# macOS
+.DS_Store
+
+# QA / verify pipeline artifacts (/qa, /vf)
+.qa/
+.verify/
+# Scratch database a /qa run boots against, so it never touches host/app.db.
+qa.db*

simple_module_ai-0.0.7/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: simple_module_ai
+Version: 0.0.7
+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.7/README.md

@@ -0,0 +1,71 @@
+# 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.7/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@simple-module-py/ai",
+  "version": "0.0.7",
+  "private": true,
+  "description": "Frontend assets for the AI module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^2.0.0",
+    "@simple-module-py/ui": "*",
+    "sonner": "^2.0.0"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {}
+}

simple_module_ai-0.0.7/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "simple_module_ai"
+version = "0.0.7"
+description = "AI base module: provider-configurable Pydantic AI service layer, encrypted key storage, admin settings UI"
+requires-python = ">=3.12"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Anto Subash", email = "antosubash@live.com" }]
+keywords = ["simple-module", "ai", "llm", "pydantic-ai", "embeddings"]
+# Ranges, never `==`: an exact framework pin makes a published module
+# uninstallable in any host running a newer framework build.
+dependencies = [
+    "simple_module_core>=0.0.25,<0.1",
+    "simple_module_db>=0.0.25,<0.1",
+    "simple_module_hosting>=0.0.25,<0.1",
+    # Floor verified: register_module_settings and apply_changes_and_reload
+    # both exist at 0.0.25.
+    "simple_module_settings>=0.0.25,<0.1",
+    "pydantic-ai-slim[anthropic,openai,google]>=2.0,<3",
+    "pydantic-settings>=2.0",
+    "cryptography>=42.0",
+]
+
+[project.urls]
+Repository = "https://github.com/antosubash/simple_module_python_modules"
+
+[project.entry-points.simple_module]
+ai = "sm_ai.module:AiModule"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "simple_module_test>=0.0.25,<0.1"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sm_ai"]
+
+# package.json lives at the module root so npm workspaces see it; copying it
+# into the package lets the host discover JS deps after a pip install. This
+# module ships no bundled frontend build, so there is no dist to include.
+[tool.hatch.build.targets.wheel.force-include]
+"package.json" = "sm_ai/package.json"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

simple_module_ai-0.0.7/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>
+  );
+}

simple_module_ai-0.0.7/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"})

simple_module_ai-0.0.7/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",
+]

simple_module_ai-0.0.7/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."
+        )