stapel-agent 0.1.0__py3-none-any.whl

stapel_agent/__init__.py

@@ -0,0 +1,55 @@
+"""stapel-agent — LLM facade: completion, translation, prompt cache/ledger.
+
+Public API (lazily resolved, PEP 562 — importing this package pulls in
+no Django code until an attribute is actually accessed):
+
+    agent_settings        — the ``STAPEL_AGENT`` settings namespace
+    complete              — raw LLM completion (cache + PromptLog ledger)
+    translate             — key-value translation flow
+    LlmProvider           — base class for custom LLM backends
+    ProviderResult        — completion text + token accounting dataclass
+    CachePolicy           — base class for custom prompt-cache policies
+    register_provider     — runtime provider registration (apps.ready())
+    registered_providers  — the effective provider registry mapping
+"""
+
+__all__ = [
+    "CachePolicy",
+    "LlmProvider",
+    "ProviderResult",
+    "agent_settings",
+    "complete",
+    "register_provider",
+    "registered_providers",
+    "translate",
+]
+
+# name -> (relative module, attribute)
+_EXPORTS = {
+    "agent_settings": (".conf", "agent_settings"),
+    "complete": (".services", "complete"),
+    "translate": (".services", "translate"),
+    "LlmProvider": (".providers.base", "LlmProvider"),
+    "ProviderResult": (".providers.base", "ProviderResult"),
+    "CachePolicy": (".cache", "CachePolicy"),
+    "register_provider": (".providers", "register_provider"),
+    "registered_providers": (".providers", "registered_providers"),
+}
+
+
+def __getattr__(name):
+    try:
+        module_path, attr = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(
+            f"module {__name__!r} has no attribute {name!r}"
+        ) from None
+    from importlib import import_module
+
+    value = getattr(import_module(module_path, __name__), attr)
+    globals()[name] = value  # cache: subsequent lookups skip __getattr__
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_agent/admin.py

@@ -0,0 +1,35 @@
+from django.contrib import admin
+
+from .models import PromptLog
+
+
+@admin.register(PromptLog)
+class PromptLogAdmin(admin.ModelAdmin):
+    """Read-only: PromptLog is an immutable ledger — rows are written by
+    the service layer only (editing one would corrupt token accounting
+    and could poison the prompt cache)."""
+
+    list_display = [
+        "created_at",
+        "source",
+        "model",
+        "model_size",
+        "status",
+        "input_tokens",
+        "output_tokens",
+        "duration_ms",
+        "user_id",
+    ]
+    list_filter = ["source", "status", "model_size"]
+    search_fields = ["prompt", "user_id", "model"]
+    date_hierarchy = "created_at"
+    ordering = ["-created_at"]
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        return False

stapel_agent/apps.py

@@ -0,0 +1,17 @@
+from django.apps import AppConfig
+
+
+class AgentConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "stapel_agent"
+    label = "agent"
+    verbose_name = "Stapel Agent"
+
+    def ready(self):
+        # comm Function providers (in-process in a monolith, transport
+        # chosen by STAPEL_COMM in microservices — same code).
+        from . import functions  # noqa: F401
+
+        # Django system checks (provider registry / DEFAULT_PROVIDER
+        # misconfiguration) — registered on import.
+        from . import checks  # noqa: F401

stapel_agent/cache.py

@@ -0,0 +1,85 @@
+"""Cache-policy seam — swap the prompt cache without forking.
+
+``STAPEL_AGENT["CACHE_POLICY"]`` is a dotted path to a ``CachePolicy``
+subclass (resolved via ``import_strings``, instantiated per call). The
+default, ``PromptLogCachePolicy``, implements the stock behaviour: the
+latest successful ``PromptLog`` row with an identical
+prompt+system_prompt+source within ``CACHE_TTL``, gated per source by
+``CACHE_LOOKUP``.
+
+Hosts can point the setting at a Redis-backed policy, a no-op policy,
+or anything else::
+
+    # myproject/llm_cache.py
+    from stapel_agent.cache import CachePolicy
+
+    class RedisCachePolicy(CachePolicy):
+        def should_cache(self, source): ...
+        def lookup(self, prompt, system_prompt, source): ...
+        def store(self, prompt, system_prompt, source, response): ...
+
+    # settings.py
+    STAPEL_AGENT = {"CACHE_POLICY": "myproject.llm_cache.RedisCachePolicy"}
+
+The PromptLog *ledger* row is always written regardless of the policy —
+caching is a read seam, accounting is not optional. ``store()`` exists
+for policies with their own storage; the default is a no-op because the
+ledger row IS the default policy's storage.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import timedelta
+
+
+class CachePolicy(ABC):
+    """Decides when to consult the prompt cache and answers lookups."""
+
+    @abstractmethod
+    def should_cache(self, source: str) -> bool:
+        """Whether *source* ("llm_facade"/"translate"/...) uses the cache."""
+
+    @abstractmethod
+    def lookup(self, prompt: str, system_prompt: str | None, source: str) -> str | None:
+        """Return the cached raw response text, or None on a miss."""
+
+    def store(self, prompt: str, system_prompt: str | None, source: str, response: str) -> None:
+        """Persist a successful response for future lookups.
+
+        No-op by default: the default policy reads the PromptLog ledger
+        row that ``services.complete`` writes anyway. Policies with
+        external storage (Redis, ...) override this.
+        """
+
+
+class PromptLogCachePolicy(CachePolicy):
+    """Stock policy: PromptLog rows + CACHE_LOOKUP/CACHE_TTL settings."""
+
+    def should_cache(self, source: str) -> bool:
+        from .conf import agent_settings
+
+        return bool((agent_settings.CACHE_LOOKUP or {}).get(source, False))
+
+    def lookup(self, prompt: str, system_prompt: str | None, source: str) -> str | None:
+        from django.utils import timezone
+
+        from .conf import agent_settings
+        from .models import PromptLog, PromptStatus
+
+        ttl = int(agent_settings.CACHE_TTL)
+        qs = PromptLog.objects.filter(
+            prompt=prompt,
+            source=source,
+            status=PromptStatus.SUCCESS,
+            response__isnull=False,
+            created_at__gte=timezone.now() - timedelta(seconds=ttl),
+        )
+        if system_prompt:
+            qs = qs.filter(system_prompt=system_prompt)
+        else:
+            qs = qs.filter(system_prompt__isnull=True)
+        row = qs.order_by("-created_at").first()
+        return row.response if row is not None else None
+
+
+__all__ = ["CachePolicy", "PromptLogCachePolicy"]

stapel_agent/checks.py

@@ -0,0 +1,77 @@
+"""Django system checks — catch provider misconfiguration at startup.
+
+Registered from ``AgentConfig.ready()``. IDs:
+
+- ``stapel_agent.E001`` — ``DEFAULT_PROVIDER`` names a provider that is
+  not in the effective registry (built-ins ← settings merge ← runtime).
+- ``stapel_agent.W001`` — a registry entry's dotted path fails to import
+  (typo, or an optional dependency missing in this image).
+- ``stapel_agent.W002`` — a registry entry resolves to something that is
+  not an ``LlmProvider`` subclass.
+
+Import/subclass problems are warnings, not errors, on purpose: providers
+resolve lazily per request and degrade to ``status: "failure"`` — a
+broken *unused* entry must not block deploys, but it should be visible.
+"""
+from __future__ import annotations
+
+import inspect
+
+from django.core import checks
+from django.utils.module_loading import import_string
+
+
+@checks.register("stapel_agent")
+def check_providers(app_configs, **kwargs):
+    from .conf import agent_settings
+    from .providers import registered_providers
+    from .providers.base import LlmProvider
+
+    issues = []
+    effective = registered_providers()
+
+    default = agent_settings.DEFAULT_PROVIDER
+    if default not in effective:
+        issues.append(
+            checks.Error(
+                f"STAPEL_AGENT['DEFAULT_PROVIDER'] is {default!r}, which is "
+                "not in the effective provider registry "
+                f"({sorted(effective) or 'empty'}).",
+                hint=(
+                    "Add it via STAPEL_AGENT['PROVIDERS'] or "
+                    "stapel_agent.providers.register_provider(), or point "
+                    "DEFAULT_PROVIDER at an existing name."
+                ),
+                id="stapel_agent.E001",
+            )
+        )
+
+    for name, target in effective.items():
+        if isinstance(target, str):
+            try:
+                target = import_string(target)
+            except ImportError as exc:
+                issues.append(
+                    checks.Warning(
+                        f"LLM provider {name!r} cannot be imported: {exc}",
+                        hint=(
+                            "Fix the dotted path, install the missing "
+                            "dependency, or remove the entry (set it to None)."
+                        ),
+                        id="stapel_agent.W001",
+                    )
+                )
+                continue
+        if not (inspect.isclass(target) and issubclass(target, LlmProvider)):
+            issues.append(
+                checks.Warning(
+                    f"LLM provider {name!r} resolves to {target!r}, which is "
+                    "not a stapel_agent.LlmProvider subclass.",
+                    hint="Implement the LlmProvider ABC (see MODULE.md).",
+                    id="stapel_agent.W002",
+                )
+            )
+    return issues
+
+
+__all__ = ["check_providers"]

stapel_agent/conf.py

@@ -0,0 +1,70 @@
+"""Settings namespace for stapel-agent.
+
+All configuration is read through ``agent_settings`` (lazily, at call
+time) instead of module-level ``os.getenv`` — so tests and host projects
+can override any key via ``settings.STAPEL_AGENT``, a flat Django setting
+of the same name, or an environment variable::
+
+    STAPEL_AGENT = {
+        "DEFAULT_PROVIDER": "openai-compat",
+        "OPENAI_COMPAT_BASE_URL": "https://api.deepseek.com/v1",
+        "OPENAI_COMPAT_API_KEY": "sk-...",
+        "OPENAI_COMPAT_MODELS": {"small": "deepseek-chat"},
+    }
+
+``PROVIDERS`` entries are **merged over** the built-in registry
+(``stapel_agent.providers.BUILTIN_PROVIDERS``) — adding one custom
+provider does not require restating the built-ins, and setting a name to
+``None``/``""`` removes it. Values are dotted paths to ``LlmProvider``
+subclasses, resolved lazily per request in ``services.get_provider``
+(not via ``import_strings`` — an unknown or broken provider must degrade
+to a ``status: failure`` response, never an import-time crash).
+"""
+from stapel_core.conf import AppSettings
+
+agent_settings = AppSettings(
+    "STAPEL_AGENT",
+    defaults={
+        # Size → model-name map used by the default (Anthropic-flavoured)
+        # providers. OpenAI-compatible hosts override per-size names via
+        # OPENAI_COMPAT_MODELS instead.
+        "MODELS": {
+            "small": "claude-haiku-4-5-20251001",
+            "medium": "claude-sonnet-5",
+            "large": "claude-opus-4-8",
+        },
+        # Overlay merged OVER providers.BUILTIN_PROVIDERS (anthropic /
+        # openai-compat / claude-code): add or override entries here,
+        # None/"" removes a name. Resolved lazily per request via
+        # import_string in services.get_provider(name).
+        "PROVIDERS": {},
+        "DEFAULT_PROVIDER": "anthropic",
+        # Anthropic SDK (read lazily at call time, never frozen at import).
+        "ANTHROPIC_API_KEY": "",
+        # Any OpenAI-compatible /chat/completions endpoint
+        # (OpenAI, DeepSeek, MiMo, GLM, Kimi, ...).
+        "OPENAI_COMPAT_BASE_URL": "",
+        "OPENAI_COMPAT_API_KEY": "",
+        # Optional size → model-name map for the openai-compat provider,
+        # e.g. {"small": "gpt-4o-mini", "medium": "gpt-4o"}. Missing sizes
+        # fall back to MODELS[size].
+        "OPENAI_COMPAT_MODELS": {},
+        # Claude Code CLI provider (opt-in only, never the default).
+        "CLI_BINARY": "claude",
+        "CLI_TIMEOUT": 120,
+        "MAX_TOKENS": 4096,
+        # Per-source cache-by-prompt toggle: a repeated identical
+        # prompt+system_prompt within CACHE_TTL returns the stored response
+        # without calling the provider.
+        "CACHE_LOOKUP": {"llm_facade": False, "translate": True},
+        # Seconds; cached rows older than this are ignored (7 days).
+        "CACHE_TTL": 604800,
+        # Dotted path to a stapel_agent.cache.CachePolicy subclass — the
+        # cache seam. The default implements the PromptLog+TTL behaviour;
+        # swap for Redis/no-op without forking.
+        "CACHE_POLICY": "stapel_agent.cache.PromptLogCachePolicy",
+    },
+    import_strings=("CACHE_POLICY",),
+)
+
+__all__ = ["agent_settings"]

stapel_agent/conftest.py

@@ -0,0 +1,123 @@
+def pytest_configure(config):
+    from django.conf import settings
+    if not settings.configured:
+        settings.configure(
+            SECRET_KEY="test-secret-key-not-for-production",
+            INSTALLED_APPS=[
+                "django.contrib.contenttypes",
+                "django.contrib.auth",
+                "django.contrib.sessions",
+                "django.contrib.messages",
+                # contrib.admin so the ModelAdmin registrations in admin.py
+                # are importable (and covered) in tests.
+                "django.contrib.admin",
+                "stapel_core.django.users",
+                "rest_framework",
+                "stapel_agent",
+            ],
+            AUTH_USER_MODEL="users.User",
+            DATABASES={
+                "default": {
+                    "ENGINE": "django.db.backends.sqlite3",
+                    "NAME": ":memory:",
+                }
+            },
+            DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+            USE_TZ=True,
+            ROOT_URLCONF="stapel_agent.tests.urls",
+            CACHES={
+                "default": {
+                    "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+                }
+            },
+            # In-memory bus — no Kafka/Redis broker needed
+            STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+            # Synchronous in-process comm and schema validation ON so
+            # llm.complete / llm.translate payloads are checked against
+            # schemas/functions/*.json in tests.
+            STAPEL_COMM={
+                "OUTBOX_ENABLED": False,
+                "ACTION_TRANSPORT": "inprocess",
+                "FUNCTION_TRANSPORT": "inprocess",
+                "VALIDATE_SCHEMAS": True,
+            },
+            MIDDLEWARE=[
+                "django.middleware.common.CommonMiddleware",
+                "stapel_core.django.jwt.middleware.ServiceAPIKeyMiddleware",
+            ],
+            SERVICE_API_KEY="test-service-key",
+            # Skip migrations — create tables directly from models
+            MIGRATION_MODULES={
+                "users": None,
+                "agent": None,
+            },
+        )
+        import django
+        django.setup()
+
+        # Register schemas/functions/*.json with the comm registries so
+        # call() payloads are validated against the committed contracts.
+        from stapel_core.comm.schemas import autoload_schemas
+        autoload_schemas()
+
+
+import pytest  # noqa: E402
+
+
+@pytest.fixture
+def user(db):
+    from django.contrib.auth import get_user_model
+    User = get_user_model()
+    return User.objects.create_user(
+        username="testuser",
+        email="testuser@example.com",
+        password="testpass123",
+    )
+
+
+@pytest.fixture
+def staff_user(db):
+    from django.contrib.auth import get_user_model
+    User = get_user_model()
+    return User.objects.create_user(
+        username="staffuser",
+        email="staff@example.com",
+        password="testpass123",
+        is_staff=True,
+    )
+
+
+@pytest.fixture
+def api_client():
+    from rest_framework.test import APIClient
+    return APIClient()
+
+
+@pytest.fixture
+def staff_client(staff_user):
+    from rest_framework.test import APIClient
+    client = APIClient()
+    client.force_authenticate(user=staff_user)
+    return client
+
+
+@pytest.fixture
+def fake_provider(settings):
+    """Route completions to the recording FakeProvider (default provider).
+
+    Keys are read lazily through stapel_agent.conf.agent_settings, so the
+    settings override takes effect at call time. Class-level state is
+    reset around each test — get_provider() instantiates a fresh object
+    per request, so recordings must live on the class.
+    """
+    from stapel_agent.tests.fakes import FakeProvider
+
+    # Merge semantics: adding "fake" does not restate the built-ins —
+    # they stay resolvable alongside it.
+    settings.STAPEL_AGENT = {
+        "PROVIDERS": {"fake": "stapel_agent.tests.fakes.FakeProvider"},
+        "DEFAULT_PROVIDER": "fake",
+    }
+    FakeProvider.reset()
+    yield FakeProvider
+    FakeProvider.reset()

stapel_agent/dto.py

@@ -0,0 +1,55 @@
+"""DTOs for the agent API."""
+
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+
+@dataclass
+class CompleteRequest:
+    """JSON LLM completion request.
+
+    Attributes:
+        prompt: The user prompt sent to the model.
+        model: Model size — small, medium or large. Example: small
+        provider: Provider name from STAPEL_AGENT["PROVIDERS"]; defaults
+            to DEFAULT_PROVIDER.
+        system_prompt: Replaces the built-in JSON-API system prompt.
+    """
+
+    prompt: str
+    model: str
+    provider: Optional[str] = None
+    system_prompt: Optional[str] = None
+
+
+@dataclass
+class TranslateRequest:
+    """Key-value translation request.
+
+    The wire key for the source language is ``from`` (a Python keyword) —
+    the serializer maps it onto ``from_lang`` explicitly.
+
+    Attributes:
+        from_lang: Source language code, or "auto" to auto-detect.
+        to: Target language code. Example: de
+        entries: Mapping of keys to source-language strings.
+    """
+
+    from_lang: str
+    to: str
+    entries: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class TranslateResponse:
+    """Key-value translation response (iron-agent contract).
+
+    Attributes:
+        status: "ok" or "failure".
+        result: Mapping of keys to translated strings (on success).
+        reason: Failure reason (on failure).
+    """
+
+    status: str
+    result: Optional[Dict[str, str]] = None
+    reason: Optional[str] = None

stapel_agent/errors.py

@@ -0,0 +1,21 @@
+"""Custom error keys for the agent service.
+
+Only *request validation* problems are error-key responses (HTTP 400).
+LLM/provider failures are NOT errors at the HTTP layer — the iron-agent
+contract returns HTTP 200 with ``{"status": "failure", "reason": ...}``.
+"""
+
+from stapel_core.django.api.errors import ErrorKeysView, register_service_errors
+
+ERR_400_INVALID_MODEL_SIZE = "error.400.invalid_model_size"
+
+AGENT_ERRORS = {
+    ERR_400_INVALID_MODEL_SIZE: "Model must be one of: small, medium, large",
+}
+
+register_service_errors(AGENT_ERRORS)
+
+
+class AgentErrorKeysView(ErrorKeysView):
+    def get_service_errors(self):
+        return AGENT_ERRORS

stapel_agent/functions.py

@@ -0,0 +1,93 @@
+"""comm Function providers of the agent module.
+
+Registered from ``AgentConfig.ready()`` (importing this module is enough:
+re-imports are no-ops and re-registering the same handler object is
+idempotent). Other modules call these by name via ``stapel_core.comm.call``
+— no import of this package needed, and in a monolith the call is
+in-process without HTTP:
+
+    from stapel_core.comm import call
+
+    call("llm.translate", {"from_lang": "auto", "to": "de", "entries": {...}})
+"""
+import logging
+
+from stapel_core.comm import function
+
+logger = logging.getLogger(__name__)
+
+COMPLETE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "prompt": {"type": "string", "description": "The user prompt."},
+        "model": {
+            "type": "string",
+            "enum": ["small", "medium", "large"],
+            "description": "Model size, mapped via STAPEL_AGENT['MODELS'].",
+        },
+        "system_prompt": {
+            "type": "string",
+            "description": "Replaces the built-in JSON-API system prompt.",
+        },
+        "provider": {
+            "type": "string",
+            "description": "Provider name from STAPEL_AGENT['PROVIDERS'].",
+        },
+    },
+    "required": ["prompt", "model"],
+    "additionalProperties": False,
+}
+
+TRANSLATE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "from_lang": {
+            "type": "string",
+            "description": "Source language code, or 'auto' to auto-detect.",
+        },
+        "to": {"type": "string", "description": "Target language code."},
+        "entries": {
+            "type": "object",
+            "additionalProperties": {"type": "string"},
+            "description": "Mapping of keys to source-language strings.",
+        },
+    },
+    "required": ["from_lang", "to", "entries"],
+    "additionalProperties": False,
+}
+
+
+@function("llm.complete", schema=COMPLETE_SCHEMA)
+def llm_complete(payload: dict) -> dict:
+    """JSON LLM completion — same result dict as ``POST api/llm/complete``.
+
+    Payload: ``{"prompt": str, "model": "small"|"medium"|"large",
+    "system_prompt"?: str, "provider"?: str}``. Returns
+    ``{"status": "ok"|"failure", "result"?: object, "comment"?: str,
+    "reason"?: str, "usage"?: {...}}``.
+    """
+    from . import services
+
+    return services.complete_json(
+        payload["prompt"],
+        payload["model"],
+        system_prompt=payload.get("system_prompt"),
+        provider=payload.get("provider"),
+    )
+
+
+@function("llm.translate", schema=TRANSLATE_SCHEMA)
+def llm_translate(payload: dict) -> dict:
+    """Key-value translation — same result dict as ``POST api/llm/translate``.
+
+    Payload: ``{"from_lang": str, "to": str, "entries": {key: text}}``.
+    Returns ``{"status": "ok", "result": {key: translated}}`` or
+    ``{"status": "failure", "reason": str}``.
+    """
+    from . import services
+
+    return services.translate(
+        payload["from_lang"],
+        payload["to"],
+        payload["entries"],
+    )

stapel_agent/migrations/0001_initial.py

@@ -0,0 +1,43 @@
+# Generated by Django 6.0.6 on 2026-07-03 20:16
+
+import uuid
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='PromptLog',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('source', models.CharField(choices=[('llm_facade', 'LLM Facade'), ('translate', 'Translate'), ('other', 'Other')], db_index=True, max_length=32)),
+                ('model', models.CharField(max_length=128)),
+                ('model_size', models.CharField(max_length=16)),
+                ('prompt', models.TextField()),
+                ('system_prompt', models.TextField(blank=True, null=True)),
+                ('response', models.TextField(blank=True, null=True)),
+                ('status', models.CharField(choices=[('success', 'Success'), ('failure', 'Failure'), ('timeout', 'Timeout'), ('error', 'Error')], db_index=True, max_length=16)),
+                ('error_message', models.TextField(blank=True, null=True)),
+                ('input_tokens', models.IntegerField(blank=True, null=True)),
+                ('output_tokens', models.IntegerField(blank=True, null=True)),
+                ('thinking_tokens', models.IntegerField(blank=True, null=True)),
+                ('cache_read_tokens', models.IntegerField(blank=True, null=True)),
+                ('cache_write_tokens', models.IntegerField(blank=True, null=True)),
+                ('duration_ms', models.IntegerField(blank=True, null=True)),
+                ('user_id', models.CharField(blank=True, db_index=True, max_length=64, null=True)),
+                ('metadata', models.JSONField(blank=True, null=True)),
+                ('created_at', models.DateTimeField(auto_now_add=True, db_index=True)),
+            ],
+            options={
+                'db_table': 'agent_prompt_log',
+                'ordering': ['-created_at'],
+                'indexes': [models.Index(fields=['source', '-created_at'], name='agent_source_created_idx')],
+            },
+        ),
+    ]