stapel-agent 0.1.0__tar.gz

stapel_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 usestapel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stapel_agent-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: stapel-agent
+Version: 0.1.0
+Summary: LLM facade Django app for the Stapel framework
+License: MIT
+Keywords: django,stapel,llm,anthropic,openai,translation
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.4,>=0.3.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.34; extra == "anthropic"
+Provides-Extra: all
+Requires-Dist: stapel-agent[anthropic]; extra == "all"
+Dynamic: license-file
+
+# stapel-agent
+
+[![CI](https://github.com/usestapel/stapel-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-agent/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/usestapel/stapel-agent/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-agent)
+
+> LLM facade — one JSON-completion/translation surface in front of swappable model providers, with a prompt cache and a token ledger
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps for building production-grade platforms.
+
+Python port of the `iron-agent` NestJS service. Same HTTP paths and contracts
+(`stapel-translate`'s `AgentProvider` keeps working unchanged), plus a comm
+surface so monolith deployments call it in-process without HTTP.
+
+## Installation
+
+```bash
+pip install stapel-agent            # core
+pip install stapel-agent[anthropic] # + the Anthropic SDK for the default provider
+```
+
+## Quick start
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'stapel_agent',
+]
+
+STAPEL_AGENT = {
+    "ANTHROPIC_API_KEY": "sk-ant-...",
+}
+
+# urls.py — paths stay 1:1 with iron-agent under the agent/ mount
+urlpatterns = [
+    ...
+    path("agent/", include("stapel_agent.urls")),
+]
+```
+
+Two surfaces, same contracts:
+
+```bash
+# HTTP (service-to-service: X-API-KEY, or a staff session)
+POST /agent/api/llm/complete   {"prompt": "...", "model": "small|medium|large",
+                                "provider"?: "...", "system_prompt"?: "..."}
+POST /agent/api/llm/translate  {"from": "auto", "to": "de", "entries": {"key": "text"}}
+```
+
+```python
+# comm (in-process in a monolith, transport chosen by STAPEL_COMM)
+from stapel_core.comm import call
+
+call("llm.complete", {"prompt": "...", "model": "small"})
+call("llm.translate", {"from_lang": "auto", "to": "de", "entries": {...}})
+```
+
+Responses follow the iron-agent contract: LLM failures are **HTTP 200** with
+`{"status": "failure", "reason": ...}` — 4xx/5xx are reserved for request
+validation and auth. Successful completions return the parsed JSON in
+`result`, prose around it in `comment`, and snake_case `usage`
+(`input_tokens` / `output_tokens`).
+
+Every provider call writes a `PromptLog` row: model, size, source, status,
+duration and the full token ledger (input / output / thinking / cache-read /
+cache-write) — per-user and per-source cost accounting needs no other table.
+
+## Settings — `STAPEL_AGENT`
+
+| Key | Default | Meaning |
+|---|---|---|
+| `MODELS` | `{"small": "claude-haiku-4-5-20251001", "medium": "claude-sonnet-5", "large": "claude-opus-4-8"}` | Size → model-name map |
+| `PROVIDERS` | `{}` | Overlay **merged over** the built-in registry (anthropic / openai-compat / claude-code) — add/override entries, `None` removes one; resolved lazily per request |
+| `DEFAULT_PROVIDER` | `"anthropic"` | Provider used when a request names none |
+| `ANTHROPIC_API_KEY` | `""` | Key for the Anthropic SDK provider (read lazily) |
+| `OPENAI_COMPAT_BASE_URL` | `""` | Base URL of any OpenAI-compatible endpoint |
+| `OPENAI_COMPAT_API_KEY` | `""` | Bearer token for that endpoint |
+| `OPENAI_COMPAT_MODELS` | `{}` | Optional size → model map for openai-compat (missing sizes fall back to `MODELS`) |
+| `CLI_BINARY` | `"claude"` | Claude Code CLI binary (opt-in provider only) |
+| `CLI_TIMEOUT` | `120` | Provider timeout, seconds |
+| `MAX_TOKENS` | `4096` | Completion token cap |
+| `CACHE_LOOKUP` | `{"llm_facade": False, "translate": True}` | Per-source cache-by-prompt toggle (used by the default cache policy) |
+| `CACHE_TTL` | `604800` | Cache window in seconds (7 days); older rows are ignored (default policy) |
+| `CACHE_POLICY` | `"stapel_agent.cache.PromptLogCachePolicy"` | Dotted path to a `CachePolicy` subclass — swap the prompt cache (Redis, no-op, ...) without forking |
+
+## Provider matrix
+
+| Name | Class | Backend | Needs |
+|---|---|---|---|
+| `anthropic` (default) | `providers.anthropic.AnthropicProvider` | Anthropic SDK | `anthropic` extra + `ANTHROPIC_API_KEY` |
+| `openai-compat` | `providers.openai_compat.OpenAICompatProvider` | Any `/chat/completions` dialect: OpenAI, DeepSeek, MiMo, GLM, Kimi | `OPENAI_COMPAT_BASE_URL` (+ key) |
+| `claude-code` | `providers.claude_cli.ClaudeCodeCLIProvider` | Spawns `claude -p ... --output-format json` | The CLI in the host image |
+
+**No CLI in any default path.** `claude-code` is strictly opt-in: it exists for
+hosts that ship the Claude Code CLI in their image and want the CLI to handle
+its own authentication (`provider: "claude-code"` per request, or
+`DEFAULT_PROVIDER` override). Unlike iron-agent there is no OAuth credential
+reading and no background token-refresh — that plumbing was deliberately
+dropped.
+
+### Adding, overriding and removing providers (merge semantics)
+
+`STAPEL_AGENT["PROVIDERS"]` is an **overlay merged over the built-ins**, not a
+replacement dict — adding your provider never requires restating the three
+shipped ones, and setting a name to `None` removes it:
+
+```python
+# settings.py — one line per change, built-ins stay available
+STAPEL_AGENT = {
+    "PROVIDERS": {
+        "acme": "myproject.llm.AcmeProvider",  # add a custom backend
+        "claude-code": None,                    # remove a built-in
+    },
+    "DEFAULT_PROVIDER": "acme",
+}
+```
+
+Or register at runtime from your app's `AppConfig.ready()` (highest
+precedence):
+
+```python
+from stapel_agent import register_provider
+
+register_provider("acme", AcmeProvider)  # class or dotted path
+```
+
+A custom backend is just a `stapel_agent.LlmProvider` subclass returning a
+`ProviderResult`. Django system checks (`stapel_agent.E001/W001/W002`) flag a
+`DEFAULT_PROVIDER` that is not in the effective registry, unimportable dotted
+paths and non-`LlmProvider` entries at startup. See [MODULE.md](MODULE.md)
+for the full extension-point map.
+
+## License
+
+MIT — see [LICENSE](LICENSE)

stapel_agent-0.1.0/README.md

@@ -0,0 +1,135 @@
+# stapel-agent
+
+[![CI](https://github.com/usestapel/stapel-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-agent/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/usestapel/stapel-agent/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-agent)
+
+> LLM facade — one JSON-completion/translation surface in front of swappable model providers, with a prompt cache and a token ledger
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps for building production-grade platforms.
+
+Python port of the `iron-agent` NestJS service. Same HTTP paths and contracts
+(`stapel-translate`'s `AgentProvider` keeps working unchanged), plus a comm
+surface so monolith deployments call it in-process without HTTP.
+
+## Installation
+
+```bash
+pip install stapel-agent            # core
+pip install stapel-agent[anthropic] # + the Anthropic SDK for the default provider
+```
+
+## Quick start
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'stapel_agent',
+]
+
+STAPEL_AGENT = {
+    "ANTHROPIC_API_KEY": "sk-ant-...",
+}
+
+# urls.py — paths stay 1:1 with iron-agent under the agent/ mount
+urlpatterns = [
+    ...
+    path("agent/", include("stapel_agent.urls")),
+]
+```
+
+Two surfaces, same contracts:
+
+```bash
+# HTTP (service-to-service: X-API-KEY, or a staff session)
+POST /agent/api/llm/complete   {"prompt": "...", "model": "small|medium|large",
+                                "provider"?: "...", "system_prompt"?: "..."}
+POST /agent/api/llm/translate  {"from": "auto", "to": "de", "entries": {"key": "text"}}
+```
+
+```python
+# comm (in-process in a monolith, transport chosen by STAPEL_COMM)
+from stapel_core.comm import call
+
+call("llm.complete", {"prompt": "...", "model": "small"})
+call("llm.translate", {"from_lang": "auto", "to": "de", "entries": {...}})
+```
+
+Responses follow the iron-agent contract: LLM failures are **HTTP 200** with
+`{"status": "failure", "reason": ...}` — 4xx/5xx are reserved for request
+validation and auth. Successful completions return the parsed JSON in
+`result`, prose around it in `comment`, and snake_case `usage`
+(`input_tokens` / `output_tokens`).
+
+Every provider call writes a `PromptLog` row: model, size, source, status,
+duration and the full token ledger (input / output / thinking / cache-read /
+cache-write) — per-user and per-source cost accounting needs no other table.
+
+## Settings — `STAPEL_AGENT`
+
+| Key | Default | Meaning |
+|---|---|---|
+| `MODELS` | `{"small": "claude-haiku-4-5-20251001", "medium": "claude-sonnet-5", "large": "claude-opus-4-8"}` | Size → model-name map |
+| `PROVIDERS` | `{}` | Overlay **merged over** the built-in registry (anthropic / openai-compat / claude-code) — add/override entries, `None` removes one; resolved lazily per request |
+| `DEFAULT_PROVIDER` | `"anthropic"` | Provider used when a request names none |
+| `ANTHROPIC_API_KEY` | `""` | Key for the Anthropic SDK provider (read lazily) |
+| `OPENAI_COMPAT_BASE_URL` | `""` | Base URL of any OpenAI-compatible endpoint |
+| `OPENAI_COMPAT_API_KEY` | `""` | Bearer token for that endpoint |
+| `OPENAI_COMPAT_MODELS` | `{}` | Optional size → model map for openai-compat (missing sizes fall back to `MODELS`) |
+| `CLI_BINARY` | `"claude"` | Claude Code CLI binary (opt-in provider only) |
+| `CLI_TIMEOUT` | `120` | Provider timeout, seconds |
+| `MAX_TOKENS` | `4096` | Completion token cap |
+| `CACHE_LOOKUP` | `{"llm_facade": False, "translate": True}` | Per-source cache-by-prompt toggle (used by the default cache policy) |
+| `CACHE_TTL` | `604800` | Cache window in seconds (7 days); older rows are ignored (default policy) |
+| `CACHE_POLICY` | `"stapel_agent.cache.PromptLogCachePolicy"` | Dotted path to a `CachePolicy` subclass — swap the prompt cache (Redis, no-op, ...) without forking |
+
+## Provider matrix
+
+| Name | Class | Backend | Needs |
+|---|---|---|---|
+| `anthropic` (default) | `providers.anthropic.AnthropicProvider` | Anthropic SDK | `anthropic` extra + `ANTHROPIC_API_KEY` |
+| `openai-compat` | `providers.openai_compat.OpenAICompatProvider` | Any `/chat/completions` dialect: OpenAI, DeepSeek, MiMo, GLM, Kimi | `OPENAI_COMPAT_BASE_URL` (+ key) |
+| `claude-code` | `providers.claude_cli.ClaudeCodeCLIProvider` | Spawns `claude -p ... --output-format json` | The CLI in the host image |
+
+**No CLI in any default path.** `claude-code` is strictly opt-in: it exists for
+hosts that ship the Claude Code CLI in their image and want the CLI to handle
+its own authentication (`provider: "claude-code"` per request, or
+`DEFAULT_PROVIDER` override). Unlike iron-agent there is no OAuth credential
+reading and no background token-refresh — that plumbing was deliberately
+dropped.
+
+### Adding, overriding and removing providers (merge semantics)
+
+`STAPEL_AGENT["PROVIDERS"]` is an **overlay merged over the built-ins**, not a
+replacement dict — adding your provider never requires restating the three
+shipped ones, and setting a name to `None` removes it:
+
+```python
+# settings.py — one line per change, built-ins stay available
+STAPEL_AGENT = {
+    "PROVIDERS": {
+        "acme": "myproject.llm.AcmeProvider",  # add a custom backend
+        "claude-code": None,                    # remove a built-in
+    },
+    "DEFAULT_PROVIDER": "acme",
+}
+```
+
+Or register at runtime from your app's `AppConfig.ready()` (highest
+precedence):
+
+```python
+from stapel_agent import register_provider
+
+register_provider("acme", AcmeProvider)  # class or dotted path
+```
+
+A custom backend is just a `stapel_agent.LlmProvider` subclass returning a
+`ProviderResult`. Django system checks (`stapel_agent.E001/W001/W002`) flag a
+`DEFAULT_PROVIDER` that is not in the effective registry, unimportable dotted
+paths and non-`LlmProvider` entries at startup. See [MODULE.md](MODULE.md)
+for the full extension-point map.
+
+## License
+
+MIT — see [LICENSE](LICENSE)

stapel_agent-0.1.0/__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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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"]