dacli-ai 0.4.0__tar.gz

dacli_ai-0.4.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: dacli-ai
+Version: 0.4.0
+Summary: Provider LLM client and token/pricing accounting for dacli
+Author-email: Mouad Jaouhari <github@mj-dev.net>
+Project-URL: Homepage, https://github.com/mouadja02/dacli
+Keywords: llm,anthropic,openai,token accounting
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic<1,>=0.40
+Requires-Dist: openai<3,>=1.40
+Requires-Dist: httpx<1,>=0.27
+
+# dacli-ai
+
+Provider LLM client (anthropic / openai / openrouter) and token/pricing accounting
+for [dacli](https://github.com/mouadja02/dacli). The leaf wheel — no dacli-core
+dependency. Embed it with `dacli-core` for a headless agent.

dacli_ai-0.4.0/README.md

@@ -0,0 +1,5 @@
+# dacli-ai
+
+Provider LLM client (anthropic / openai / openrouter) and token/pricing accounting
+for [dacli](https://github.com/mouadja02/dacli). The leaf wheel — no dacli-core
+dependency. Embed it with `dacli-core` for a headless agent.

dacli_ai-0.4.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dacli-ai"
+dynamic = ["version"]
+description = "Provider LLM client and token/pricing accounting for dacli"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Mouad Jaouhari", email = "github@mj-dev.net" }]
+keywords = ["llm", "anthropic", "openai", "token accounting"]
+# The leaf wheel: provider SDKs + the pricing fetch. The SDKs are base — the
+# client is inert without one. httpx backs the models.dev pricing lookup.
+dependencies = [
+    "anthropic>=0.40,<1",
+    "openai>=1.40,<3",
+    "httpx>=0.27,<1",
+]
+
+[project.urls]
+Homepage = "https://github.com/mouadja02/dacli"
+
+[tool.setuptools.dynamic]
+version = { attr = "dacli.ai.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["dacli*"]
+namespaces = true

dacli_ai-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dacli_ai-0.4.0/src/dacli/ai/__init__.py

@@ -0,0 +1,8 @@
+# dacli-ai: the provider-agnostic LLM client (ℛ) and token/pricing accounting.
+# The leaf wheel — no dacli-core import at runtime.
+
+from dacli.ai.llm import LLMClient
+
+__version__ = "0.4.0"
+
+__all__ = ["LLMClient"]

dacli_ai-0.4.0/src/dacli/ai/llm.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import random
+import asyncio
+import logging
+import contextlib
+from typing import TYPE_CHECKING, Any, TypeAlias
+from collections.abc import Awaitable, Callable
+
+from dacli.ai.providers import Provider, create_provider, unsupported_tools_error
+
+if TYPE_CHECKING:
+    # ai is the leaf wheel; it must not import core at runtime. Settings is only a
+    # type annotation here — the client reads it by attribute (duck-typed).
+    from dacli.config.settings import Settings
+
+logger = logging.getLogger(__name__)
+
+# Type of the optional streaming callback: receives each text delta as it
+# arrives. Returning None; it is presentation-only and must not raise into the
+# generate path (the UI guards its own rendering).
+OnText: TypeAlias = Callable[[str], None] | None
+
+# Type of the optional retry-status callback. Invoked once per *retry* (not on
+# the final failure) with the upcoming attempt number, the backoff delay about
+# to be slept, and the transient error that triggered it, so the TUI/logger can
+# render "⟳ retrying in 2.1s (429)".
+OnRetry = Callable[..., None] | None
+
+
+class LLMClient:
+    # Multi-provider LLM client: a thin facade that selects a Provider in
+    # initialize() and delegates request mechanics to it (A-2). The public
+    # surface (generate / classify / last_usage) is provider-agnostic; the
+    # shared retry/backoff lives here so no provider duplicates it.
+
+    def __init__(self, settings: Settings):
+        # Initialize LLM client with settings
+        self.settings = settings
+        # The concrete SDK client (AsyncOpenAI / AsyncAnthropic) owned by the
+        # active provider; mirrored here so callers (and tests) can inspect or
+        # inject it on the facade. Typed Any so provider-specific attribute
+        # access type-checks without a fragile union.
+        self._client: Any = None
+        self._provider = settings.llm.provider
+        # The active Provider implementation, selected in initialize().
+        self._provider_impl: Provider | None = None
+        # Provider-normalized token usage of the most recent generate() call,
+        # read by the kernel for cost tracking. Reset on each generate().
+        self.last_usage: dict[str, int] = {}
+
+    async def initialize(self) -> None:
+        # Select and initialize the provider. ``supports_tools`` is checked
+        # here so a provider that cannot do tool calling (which every real
+        # agent turn requires) fails fast at configuration time, not deep
+        # inside the first turn (P02, Option B — honest removal).
+        provider = create_provider(
+            self._provider.lower(), self.settings, retry=self._with_retry
+        )
+        if not provider.supports_tools:
+            raise unsupported_tools_error(provider.name)
+        await provider.initialize()
+        self._provider_impl = provider
+        self._client = provider.client
+
+    def _impl(self) -> Provider:
+        # The active provider, created lazily for paths that bypass
+        # initialize(). A fake SDK client injected on the facade (tests) is
+        # pushed through to the provider so both always see the same client.
+        impl = getattr(self, "_provider_impl", None)
+        if impl is None:
+            impl = create_provider(
+                self._provider.lower(), self.settings, retry=self._with_retry
+            )
+            self._provider_impl = impl
+        if impl.client is not self._client:
+            impl.client = self._client
+        return impl
+
+    async def generate(self, messages: list[dict[str, str]], tools: list[dict] | None = None, system_prompt: str | None = None, on_text: OnText = None, model: str | None = None, on_retry: OnRetry = None) -> tuple[str, list[dict]]:
+        """
+        Generate a response from the LLM.
+
+        Args:
+            messages: Conversation messages
+            tools: Available tool definitions
+            system_prompt: System prompt to use
+            on_text: Optional callback invoked with each text delta as it is
+                generated. When provided (and the provider supports it) the
+                response is streamed; the return value is unchanged. Providers
+                without streaming call it once with the full text instead, so
+                the UI behaves identically.
+            model: Optional per-call model override (model tiering, ℛ).
+                When None the configured ``settings.llm.model`` is used, so the
+                default single-model path is byte-for-byte unchanged. The
+                ``ModelRouter`` passes the cheap or strong tier id here.
+
+        Returns:
+            Tuple of (response content, tool calls)
+        """
+        if not self._client:
+            await self.initialize()
+
+        self.last_usage = {}  # populated from the provider below
+        model = model or self.settings.llm.model
+        impl = self._impl()
+        content, tool_calls = await impl.generate(
+            messages, tools, system_prompt, on_text=on_text, model=model, on_retry=on_retry
+        )
+        self.last_usage = impl.last_usage
+        return content, tool_calls
+
+    def _retryable_exceptions(self) -> tuple[type, ...]:
+        # The active provider's declared transient-error classes (429 rate
+        # limit, dropped connection, 5xx); an unknown provider retries nothing,
+        # so a transient blip simply surfaces unchanged.
+        try:
+            return self._impl().retryable_exceptions()
+        except ValueError:
+            return ()
+
+    @staticmethod
+    def _default_on_retry(*, attempt: int, delay: float, error: Exception) -> None:
+        # Fallback status sink when no on_retry is wired (e.g. P13 TUI absent):
+        # log the transient failure + backoff so a retried turn is never silent.
+        logger.warning(
+            "LLM call failed (%s); retrying in %.1fs (attempt %d)",
+            type(error).__name__,
+            delay,
+            attempt,
+        )
+
+    async def _with_retry(
+        self,
+        fn: Callable[[], Awaitable],
+        *,
+        attempts: int | None = None,
+        base: float | None = None,
+        on_retry: OnRetry = None,
+        retryable: tuple[type[BaseException], ...] | None = None,
+    ):
+        """Run ``fn`` with bounded, jittered exponential backoff (P05).
+
+        ``fn`` is an argument-free coroutine factory invoked once per attempt;
+        for streaming paths it re-establishes the stream from scratch on retry
+        (at-most-once-token caveat: any partial tokens already emitted to the UI
+        are discarded when the stream is restarted). Only ``retryable`` classes
+        are retried — everything else propagates immediately (fail fast).
+        """
+        attempts = attempts or self.settings.llm.retry_attempts
+        base = base if base is not None else self.settings.llm.retry_base_delay
+        retryable = retryable if retryable is not None else self._retryable_exceptions()
+        on_retry = on_retry or self._default_on_retry
+        for i in range(attempts):
+            try:
+                return await fn()
+            except retryable as e:
+                if i == attempts - 1:
+                    raise
+                delay = base * 2 ** i + random.random() * 0.3
+                # a status sink must never break the retry loop
+                with contextlib.suppress(Exception):
+                    on_retry(attempt=i + 1, delay=delay, error=e)
+                await asyncio.sleep(delay)
+        # Unreachable: attempts >= 1, so the loop always returns or raises. Kept
+        # so the function provably never returns None.
+        raise RuntimeError("_with_retry exhausted without returning or raising")
+
+    async def _stream_openai(self, request_kwargs: dict, on_text: OnText, on_retry: OnRetry = None) -> tuple[str, list[dict]]:
+        # Back-compat seam: the OpenAI-compatible streaming path is also driven
+        # directly through the facade (tests inject a fake SDK client on
+        # ``_client``). Delegates to the provider; identical to generate()'s
+        # streaming path.
+        impl = self._impl()
+        result = await impl._stream(request_kwargs, on_text, on_retry=on_retry)
+        self.last_usage = impl.last_usage
+        return result
+
+    async def classify(self, text: str, labels: list[str], instructions: str | None = None, model: str | None = None) -> str:
+        """
+        Thin classification helper used by the router.
+
+        Sends a tool-free completion asking the model to pick exactly one label
+        from ``labels`` and normalizes the answer back onto that set when possible.
+        ``model`` lets the caller force the cheap tier — classification
+        is the canonical cheap-model job.
+        """
+        system = instructions or (
+            "You are a classifier. Respond with exactly one of the allowed labels "
+            "and nothing else."
+        )
+        label_list = ", ".join(labels)
+        prompt = (
+            f"Allowed labels: {label_list}\n\n"
+            f"Text to classify:\n{text}\n\n"
+            "Respond with exactly one label from the allowed list."
+        )
+        content, _ = await self.generate(
+            messages=[{"role": "user", "content": prompt}],
+            tools=None,
+            system_prompt=system,
+            model=model,
+        )
+        answer = (content or "").strip()
+
+        # Exact (case-insensitive) match first, then substring fallback.
+        for label in labels:
+            if answer.lower() == label.lower():
+                return label
+        for label in labels:
+            if label.lower() in answer.lower():
+                return label
+        return answer

dacli_ai-0.4.0/src/dacli/ai/pricing.py

@@ -0,0 +1,325 @@
+"""Model pricing via the models.dev API, plus token-usage accounting.
+
+dacli tracks how many tokens each LLM call consumes and what it costs. Pricing
+is looked up from https://models.dev/api.json (a community database of model
+specs/pricing), filtered to the configured provider + model. The payload is
+cached on disk with a TTL so we don't hit the network every turn, and we degrade
+gracefully when offline (tokens are still tracked; cost is reported as unknown).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import tempfile
+import time
+from dataclasses import dataclass
+from difflib import SequenceMatcher
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+
+def _write_json_atomic(path: Path, obj: Any) -> None:
+    # ai is the leaf wheel and can't reach core.atomicio. The cache is best-effort
+    # (a torn write just forces a re-fetch), but cheap crash-safety is still worth
+    # it: write a sibling temp, fsync, os.replace (atomic on POSIX + Windows).
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(json.dumps(obj))
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+MODELS_DEV_URL = "https://models.dev/api.json"
+CACHE_TTL_SECONDS = 24 * 60 * 60  # refresh pricing at most once a day
+# Short network timeout: pricing is a startup nicety, not a blocker. A
+# first-run offline user (no cache yet) must not wait long before we fall back to
+# "cost unknown". Keep it well under a human's patience threshold.
+HTTP_TIMEOUT_SECONDS = 5.0
+
+# Minimum similarity score for a fuzzy model match to be trusted. Below this we
+# return no pricing (better an honest "unknown" than a wrong, confident price).
+SIMILARITY_THRESHOLD = 0.62
+
+
+@dataclass
+class TokenUsage:
+    """Token counts for one or many LLM calls (provider-normalized)."""
+
+    input: int = 0
+    output: int = 0
+    cache_read: int = 0
+    cache_creation: int = 0
+
+    def add(self, other: TokenUsage) -> None:
+        self.input += other.input
+        self.output += other.output
+        self.cache_read += other.cache_read
+        self.cache_creation += other.cache_creation
+
+    @property
+    def total(self) -> int:
+        return self.input + self.output + self.cache_read + self.cache_creation
+
+    def as_dict(self) -> dict[str, int]:
+        return {
+            "input": self.input,
+            "output": self.output,
+            "cache_read": self.cache_read,
+            "cache_creation": self.cache_creation,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any] | None) -> TokenUsage:
+        d = d or {}
+        return cls(
+            input=int(d.get("input", 0) or 0),
+            output=int(d.get("output", 0) or 0),
+            cache_read=int(d.get("cache_read", 0) or 0),
+            cache_creation=int(d.get("cache_creation", 0) or 0),
+        )
+
+
+@dataclass
+class ModelPricing:
+    """USD cost per 1M tokens for a single model (models.dev `cost` block)."""
+
+    provider: str
+    model: str
+    input: float = 0.0
+    output: float = 0.0
+    cache_read: float = 0.0
+    cache_write: float = 0.0
+    # The models.dev entry we actually priced against. Equal to ``model`` on an
+    # exact hit; on a fuzzy hit it names the closest catalog model (e.g.
+    # ``openai/gpt-oss-120b`` for a requested ``openai/gpt-oss-120b:nitro``).
+    resolved_model: str = ""
+    resolved_provider: str = ""
+    match: str = "exact"           # "exact" | "normalized" | "similar"
+    similarity: float = 1.0
+
+    @property
+    def is_fuzzy(self) -> bool:
+        return self.match != "exact"
+
+    def cost_for(self, usage: TokenUsage) -> float:
+        """Compute USD cost for a usage record (prices are per 1M tokens)."""
+        return (
+            usage.input * self.input
+            + usage.output * self.output
+            + usage.cache_read * self.cache_read
+            + usage.cache_creation * self.cache_write
+        ) / 1_000_000
+
+
+# ----------------------------------------------------------------------------
+# models.dev lookup
+# ----------------------------------------------------------------------------
+def _ci_get(d: Any, key: str) -> Any:
+    """Case-insensitive dict lookup (model/provider ids vary in casing)."""
+    if not isinstance(d, dict) or not key:
+        return None
+    if key in d:
+        return d[key]
+    lowered = key.lower()
+    for k, v in d.items():
+        if isinstance(k, str) and k.lower() == lowered:
+            return v
+    return None
+
+
+# Provider-routing variant suffixes (OpenRouter et al.) that don't change the
+# underlying model's price — stripped before matching, e.g.
+# ``openai/gpt-oss-120b:nitro`` -> ``openai/gpt-oss-120b``.
+_VARIANT_SUFFIX_RE = re.compile(r":[^:/]+$")
+
+
+def _normalize_model_id(model: str) -> str:
+    """Lowercase + drop the routing-variant suffix for matching."""
+    s = (model or "").strip().lower()
+    # Strip a trailing ``:variant`` (nitro/floor/free/beta/extended/online/...).
+    # models.dev ids never carry a ``:`` so this only removes routing noise.
+    s = _VARIANT_SUFFIX_RE.sub("", s)
+    return s.strip()
+
+
+def _basename(model_id: str) -> str:
+    # The vendor/model -> model part ("openai/gpt-oss-120b" -> "gpt-oss-120b").
+    return model_id.rsplit("/", 1)[-1]
+
+
+def _iter_models(payload: dict, provider: str):
+    """Yield ``(provider_id, provider_entry, model_id, model_entry)``.
+
+    The configured provider's models come first so a routed model is priced
+    against *that* provider's catalog (e.g. OpenRouter pricing for an
+    OpenRouter-routed model) before falling back to other providers.
+    """
+    seen_provider = None
+    prov = _ci_get(payload, provider)
+    if isinstance(prov, dict):
+        seen_provider = next((k for k in payload if k.lower() == (provider or "").lower()), provider)
+        for mid, entry in (prov.get("models", {}) or {}).items():
+            if isinstance(entry, dict):
+                yield seen_provider, prov, mid, entry
+    for pid, pval in payload.items():
+        if pid == seen_provider or not isinstance(pval, dict):
+            continue
+        for mid, entry in (pval.get("models", {}) or {}).items():
+            if isinstance(entry, dict):
+                yield pid, pval, mid, entry
+
+
+def _score(query_norm: str, candidate_id: str) -> float:
+    """Similarity in [0,1] between a normalized query and a candidate model id."""
+    cand_norm = _normalize_model_id(candidate_id)
+    if query_norm == cand_norm:
+        return 1.0
+    # A matching basename is a strong signal even if the vendor prefix differs.
+    base_q, base_c = _basename(query_norm), _basename(cand_norm)
+    if base_q == base_c:
+        return 0.97
+    full = SequenceMatcher(None, query_norm, cand_norm).ratio()
+    base = SequenceMatcher(None, base_q, base_c).ratio()
+    # Reward containment (e.g. "gpt-oss-120b" inside "openai/gpt-oss-120b").
+    contain = 0.9 if (base_q and base_q in base_c) or (base_c and base_c in base_q) else 0.0
+    return max(full, base, contain)
+
+
+def _find_model(payload: Any, provider: str, model: str) -> tuple[dict, dict, str, str, str, float] | None:
+    """Locate the best (provider_entry, model_entry, ...) for provider+model.
+
+    Returns ``(provider_entry, model_entry, resolved_provider_id, resolved_model_id,
+    match_kind, similarity)`` or ``None``. Match resolution, in order:
+
+    1. **exact** case-insensitive id in the named provider, then any provider;
+    2. **normalized** exact (after stripping the routing-variant suffix);
+    3. **similar** — the closest catalog id by similarity, above a threshold,
+       preferring the configured provider when its best match ties.
+    """
+    if not isinstance(payload, dict) or not model:
+        return None
+
+    # 1. exact (preserves the original behavior + tests).
+    prov = _ci_get(payload, provider)
+    if isinstance(prov, dict):
+        m = _ci_get(prov.get("models", {}), model)
+        if isinstance(m, dict):
+            return prov, m, provider, model, "exact", 1.0
+    for pid, pval in payload.items():
+        if not isinstance(pval, dict):
+            continue
+        m = _ci_get(pval.get("models", {}), model)
+        if isinstance(m, dict):
+            return pval, m, pid, model, "exact", 1.0
+
+    # 2 & 3. normalized-exact + similarity over all candidates, provider-first.
+    query_norm = _normalize_model_id(model)
+    if not query_norm:
+        return None
+
+    best = None  # (score, is_same_provider, provider_id, prov_entry, model_id, entry)
+    same_provider_id = next((k for k in payload if k.lower() == (provider or "").lower()), None)
+    for pid, pval, mid, entry in _iter_models(payload, provider):
+        score = _score(query_norm, mid)
+        same = (pid == same_provider_id)
+        # A normalized-exact hit (score 1.0) wins immediately within the
+        # provider-first ordering.
+        if score >= 1.0 and same:
+            return pval, entry, pid, mid, "normalized", 1.0
+        cand = (score, same, pid, pval, mid, entry)
+        if best is None or (score, same) > (best[0], best[1]):
+            best = cand
+
+    if best and best[0] >= SIMILARITY_THRESHOLD:
+        score, _same, pid, pval, mid, entry = best
+        kind = "normalized" if score >= 1.0 else "similar"
+        return pval, entry, pid, mid, kind, round(score, 3)
+    return None
+
+
+def pricing_from_payload(payload: Any, provider: str, model: str) -> ModelPricing | None:
+    """Build :class:`ModelPricing` from an in-memory api.json payload (pure).
+
+    Falls back to a similarity search when an exact id isn't in the catalog, so
+    a routed/variant model (``…:nitro``) is priced against its closest match.
+    """
+    found = _find_model(payload, (provider or "").strip(), (model or "").strip())
+    if not found:
+        return None
+    _prov_entry, entry, resolved_provider, resolved_model, kind, similarity = found
+    cost = entry.get("cost") or {}
+    return ModelPricing(
+        provider=provider,
+        model=model,
+        input=float(cost.get("input", 0) or 0),
+        output=float(cost.get("output", 0) or 0),
+        cache_read=float(cost.get("cache_read", 0) or 0),
+        cache_write=float(cost.get("cache_write", 0) or 0),
+        resolved_model=resolved_model,
+        resolved_provider=resolved_provider,
+        match=kind,
+        similarity=similarity,
+    )
+
+
+# ----------------------------------------------------------------------------
+# cached fetch
+# ----------------------------------------------------------------------------
+def _cache_path(cache_dir: str) -> Path:
+    return Path(cache_dir) / "models_cache.json"
+
+
+def _load_cache(cache_dir: str) -> tuple[float, Any]:
+    try:
+        data = json.loads(_cache_path(cache_dir).read_text(encoding="utf-8"))
+        return float(data.get("fetched_at", 0)), data.get("payload")
+    except Exception:
+        return 0.0, None
+
+
+def _save_cache(cache_dir: str, payload: Any) -> None:
+    try:
+        path = _cache_path(cache_dir)
+        _write_json_atomic(path, {"fetched_at": time.time(), "payload": payload})
+    except Exception:
+        log.debug("pricing cache write failed", exc_info=True)  # best-effort
+
+
+def fetch_api_json(cache_dir: str = ".dacli", force_refresh: bool = False) -> Any:
+    """Return the models.dev payload, using a TTL cache and offline fallback."""
+    fetched_at, payload = _load_cache(cache_dir)
+    fresh = payload is not None and (time.time() - fetched_at) < CACHE_TTL_SECONDS
+    if fresh and not force_refresh:
+        return payload
+
+    try:
+        import httpx
+
+        resp = httpx.get(MODELS_DEV_URL, timeout=HTTP_TIMEOUT_SECONDS)
+        resp.raise_for_status()
+        payload = resp.json()
+        _save_cache(cache_dir, payload)
+        return payload
+    except Exception:
+        return payload  # stale cache or None when offline
+
+
+def fetch_pricing(
+    provider: str,
+    model: str,
+    cache_dir: str = ".dacli",
+    force_refresh: bool = False,
+) -> ModelPricing | None:
+    """Resolve pricing for provider+model, or ``None`` if unavailable/offline."""
+    payload = fetch_api_json(cache_dir, force_refresh=force_refresh)
+    return pricing_from_payload(payload, provider, model)

dacli_ai-0.4.0/src/dacli/ai/providers.py

@@ -0,0 +1,376 @@
+"""Per-provider LLM implementations behind the :class:`Provider` protocol (A-2).
+
+Each provider owns its SDK client, request shaping, streaming reassembly, and
+usage normalization, and **declares** its capabilities (``supports_tools``) so
+"does this provider support tools?" is a configure-time property, not a
+turn-time surprise. The :class:`~dacli.ai.llm.LLMClient` facade selects
+a provider in ``initialize()`` and delegates; bounded retry/backoff stays in
+the facade and is injected as ``retry`` so no provider duplicates it.
+"""
+
+from __future__ import annotations
+
+import json
+import contextlib
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, ClassVar
+
+if TYPE_CHECKING:
+    from dacli.config.settings import Settings
+    from dacli.ai.llm import OnRetry, OnText
+
+
+def emit(on_text: OnText, delta: str) -> None:
+    # Stream a delta to the UI without ever letting a rendering error break
+    # generation (reliability-first).
+    if on_text and delta:
+        with contextlib.suppress(Exception):
+            on_text(delta)
+
+
+class Provider(ABC):
+    """One LLM provider: declared capabilities + the request/stream mechanics.
+
+    ``retry`` is the facade's ``_with_retry`` (bounded, jittered exponential
+    backoff) — shared, never reimplemented per provider. ``client`` is the
+    provider's SDK client, built lazily in :meth:`initialize` with the SDK's
+    own retries disabled so the configured count is authoritative.
+    """
+
+    name: ClassVar[str] = ""
+    supports_tools: ClassVar[bool] = True
+
+    def __init__(self, settings: Settings, *, retry):
+        self.settings = settings
+        self._retry = retry
+        self.client: Any = None
+        # Provider-normalized token usage of the most recent generate() call;
+        # the facade copies it onto its own ``last_usage`` after delegating.
+        self.last_usage: dict[str, int] = {}
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Construct the SDK client (``max_retries=0`` — retry is ours)."""
+
+    @abstractmethod
+    async def generate(
+        self,
+        messages: list[dict[str, str]],
+        tools: list[dict] | None = None,
+        system_prompt: str | None = None,
+        on_text: OnText = None,
+        model: str | None = None,
+        on_retry: OnRetry = None,
+    ) -> tuple[str, list[dict]]:
+        """Return ``(content, tool_calls)`` for one completion."""
+
+    @abstractmethod
+    def normalize_usage(self, raw) -> dict[str, int]:
+        """Map the provider's raw usage object onto the shared usage dict."""
+
+    def retryable_exceptions(self) -> tuple[type, ...]:
+        # Provider-specific *transient* error classes that are safe to retry
+        # (429 rate limit, dropped connection, 5xx). Auth / 4xx-validation
+        # errors are deliberately excluded so they fail fast. Imported lazily
+        # (mirroring initialize()) and tolerant of a missing SDK -> () means
+        # "retry nothing", so a transient blip simply surfaces unchanged.
+        return ()
+
+
+class OpenAIProvider(Provider):
+    """OpenAI (and any OpenAI-compatible endpoint via ``base_url``)."""
+
+    name = "openai"
+
+    async def initialize(self) -> None:
+        from openai import AsyncOpenAI
+        self.client = AsyncOpenAI(
+            api_key=self.settings.llm.api_key,
+            base_url=self.settings.llm.base_url,
+            timeout=self.settings.llm.timeout,
+            max_retries=0,
+        )
+
+    def retryable_exceptions(self) -> tuple[type, ...]:
+        try:
+            from openai import (
+                RateLimitError,
+                APIConnectionError,
+                InternalServerError,
+            )
+        except ImportError:
+            return ()
+        return (RateLimitError, APIConnectionError, InternalServerError)
+
+    async def generate(self, messages: list[dict[str, str]], tools: list[dict] | None = None, system_prompt: str | None = None, on_text: OnText = None, model: str | None = None, on_retry: OnRetry = None) -> tuple[str, list[dict]]:
+        # Generate using OpenAI-compatibile API
+
+        # Prepare messages includes system prompt
+        full_messages = []
+        if system_prompt:
+            full_messages.append({"role": "system", "content": system_prompt})
+        full_messages.extend(messages)
+
+        # Prepare request
+        request_kwargs = {
+            "model": model or self.settings.llm.model,
+            "messages": full_messages,
+            "temperature": self.settings.llm.temperature,
+            "max_tokens": self.settings.llm.max_tokens,
+        }
+
+        # Add tools if provided
+        if tools:
+            request_kwargs["tools"] = tools
+            request_kwargs["tool_choice"] = "auto"
+
+        if on_text is not None:
+            return await self._stream(request_kwargs, on_text, on_retry=on_retry)
+
+        # Make request (retried on transient errors; permanent errors fail fast).
+        response = await self._retry(
+            lambda: self.client.chat.completions.create(**request_kwargs),
+            on_retry=on_retry,
+            retryable=self.retryable_exceptions(),
+        )
+
+        # Extract response
+        choice = response.choices[0]
+        content = choice.message.content or ""
+
+        # Extract tool calls
+        tool_calls = []
+        if hasattr(choice.message, "tool_calls") and choice.message.tool_calls:
+            tool_calls.extend(
+                {"id": tc.id, "name": tc.function.name, "arguments": json.loads(tc.function.arguments)}
+                for tc in choice.message.tool_calls
+            )
+
+        self.last_usage = self.normalize_usage(getattr(response, "usage", None))
+        return content, tool_calls
+
+    async def _stream(self, request_kwargs: dict, on_text: OnText, on_retry: OnRetry = None) -> tuple[str, list[dict]]:
+        # Streaming variant: accumulate text deltas (emitted live) and reassemble
+        # tool calls, which arrive as indexed fragments across chunks.
+        request_kwargs = {**request_kwargs, "stream": True, "stream_options": {"include_usage": True}}
+
+        # The whole stream is retried as a unit: a transient error while
+        # establishing *or* consuming the stream restarts it from scratch.
+        # at-most-once-token caveat — partial deltas already emitted to the UI on
+        # a failed attempt are discarded; the restart re-emits from the top.
+        async def _do() -> tuple[str, list[dict]]:
+            stream = await self.client.chat.completions.create(**request_kwargs)
+
+            content = ""
+            usage_obj = None
+            # index -> {"id", "name", "arguments"(str)}
+            acc: dict[int, dict[str, str]] = {}
+
+            async for chunk in stream:
+                if getattr(chunk, "usage", None):
+                    usage_obj = chunk.usage  # final usage chunk (include_usage)
+                if not chunk.choices:
+                    continue
+                delta = chunk.choices[0].delta
+                if getattr(delta, "content", None):
+                    content += delta.content
+                    emit(on_text, delta.content)
+                for tc in (getattr(delta, "tool_calls", None) or []):
+                    slot = acc.setdefault(tc.index, {"id": "", "name": "", "arguments": ""})
+                    if getattr(tc, "id", None):
+                        slot["id"] = tc.id
+                    fn = getattr(tc, "function", None)
+                    if fn is not None:
+                        if getattr(fn, "name", None):
+                            slot["name"] = fn.name
+                        if getattr(fn, "arguments", None):
+                            slot["arguments"] += fn.arguments
+
+            tool_calls = []
+            for index in sorted(acc):
+                slot = acc[index]
+                if not slot["name"]:
+                    continue
+                try:
+                    arguments = json.loads(slot["arguments"] or "{}")
+                except json.JSONDecodeError:
+                    arguments = {}
+                tool_calls.append({"id": slot["id"], "name": slot["name"], "arguments": arguments})
+
+            self.last_usage = self.normalize_usage(usage_obj)
+            return content, tool_calls
+
+        return await self._retry(_do, on_retry=on_retry, retryable=self.retryable_exceptions())
+
+    def normalize_usage(self, raw) -> dict[str, int]:
+        # OpenAI prompt_tokens includes cached tokens -> split them out so cost
+        # isn't double-counted.
+        if raw is None:
+            return {}
+        details = getattr(raw, "prompt_tokens_details", None)
+        cached = (getattr(details, "cached_tokens", 0) or 0) if details is not None else 0
+        return {
+            "input": max(0, (getattr(raw, "prompt_tokens", 0) or 0) - cached),
+            "output": getattr(raw, "completion_tokens", 0) or 0,
+            "cache_read": cached,
+            "cache_creation": 0,
+        }
+
+
+class OpenRouterProvider(OpenAIProvider):
+    """OpenRouter — OpenAI-compatible, with the OpenRouter endpoint default."""
+
+    name = "openrouter"
+
+    async def initialize(self) -> None:
+        from openai import AsyncOpenAI
+        self.client = AsyncOpenAI(
+            api_key=self.settings.llm.api_key,
+            base_url=self.settings.llm.base_url or "https://openrouter.ai/api/v1",
+            timeout=self.settings.llm.timeout,
+            max_retries=0,
+        )
+
+
+class AnthropicProvider(Provider):
+    """Anthropic Messages API."""
+
+    name = "anthropic"
+
+    async def initialize(self) -> None:
+        from anthropic import AsyncAnthropic
+        self.client = AsyncAnthropic(
+            api_key=self.settings.llm.api_key,
+            base_url=self.settings.llm.base_url,
+            timeout=self.settings.llm.timeout,
+            max_retries=0,
+        )
+
+    def retryable_exceptions(self) -> tuple[type, ...]:
+        try:
+            from anthropic import (
+                RateLimitError,
+                APIConnectionError,
+                InternalServerError,
+            )
+        except ImportError:
+            return ()
+        return (RateLimitError, APIConnectionError, InternalServerError)
+
+    async def generate(self, messages: list[dict[str, str]], tools: list[dict] | None = None, system_prompt: str | None = None, on_text: OnText = None, model: str | None = None, on_retry: OnRetry = None) -> tuple[str, list[dict]]:
+        # Generate using Anthropic API
+        # Prepare request
+        request_kwargs = {
+            "model": model or self.settings.llm.model,
+            "max_tokens": self.settings.llm.max_tokens,
+            "messages": messages,
+        }
+
+        if system_prompt:
+            request_kwargs["system"] = system_prompt
+
+        # Convert tools to Anthropic format
+        if tools:
+            request_kwargs["tools"] = [
+                {
+                    "name": tool["function"]["name"],
+                    "description": tool["function"]["description"],
+                    "input_schema": tool["function"]["parameters"]
+                }
+                for tool in tools
+            ]
+
+        if on_text is not None:
+            return await self._stream(request_kwargs, on_text, on_retry=on_retry)
+
+        async def _do() -> tuple[str, list[dict]]:
+            response = await self.client.messages.create(**request_kwargs)
+            self.last_usage = self.normalize_usage(getattr(response, "usage", None))
+            return self._extract(response.content)
+
+        return await self._retry(_do, on_retry=on_retry, retryable=self.retryable_exceptions())
+
+    async def _stream(self, request_kwargs: dict, on_text: OnText, on_retry: OnRetry = None) -> tuple[str, list[dict]]:
+        # Streaming variant: emit text events live, then read the assembled
+        # final message for the authoritative content + tool_use blocks. The
+        # whole stream is retried as a unit (see OpenAIProvider._stream for the
+        # at-most-once-token caveat on restart).
+        async def _do() -> tuple[str, list[dict]]:
+            async with self.client.messages.stream(**request_kwargs) as stream:
+                async for text in stream.text_stream:
+                    emit(on_text, text)
+                final = await stream.get_final_message()
+            self.last_usage = self.normalize_usage(getattr(final, "usage", None))
+            return self._extract(final.content)
+
+        return await self._retry(_do, on_retry=on_retry, retryable=self.retryable_exceptions())
+
+    def normalize_usage(self, raw) -> dict[str, int]:
+        # Anthropic reports cache tokens as fields separate from input_tokens.
+        if raw is None:
+            return {}
+        return {
+            "input": getattr(raw, "input_tokens", 0) or 0,
+            "output": getattr(raw, "output_tokens", 0) or 0,
+            "cache_read": getattr(raw, "cache_read_input_tokens", 0) or 0,
+            "cache_creation": getattr(raw, "cache_creation_input_tokens", 0) or 0,
+        }
+
+    @staticmethod
+    def _extract(blocks) -> tuple[str, list[dict]]:
+        content = ""
+        tool_calls = []
+        for block in blocks:
+            if block.type == "text":
+                content += block.text
+            elif block.type == "tool_use":
+                tool_calls.append({"id": block.id, "name": block.name, "arguments": block.input})
+        return content, tool_calls
+
+
+class GoogleProvider(Provider):
+    """Gemini — declared, but it never supported tool calling (P02, Option B).
+
+    ``supports_tools = False`` is the load-bearing property: the facade rejects
+    it at configure time with a clear error instead of a turn-time
+    ``NotImplementedError``. The methods below are defensive for direct use.
+    """
+
+    name = "google"
+    supports_tools = False
+
+    async def initialize(self) -> None:
+        raise unsupported_tools_error(self.name)
+
+    async def generate(self, messages: list[dict[str, str]], tools: list[dict] | None = None, system_prompt: str | None = None, on_text: OnText = None, model: str | None = None, on_retry: OnRetry = None) -> tuple[str, list[dict]]:
+        raise unsupported_tools_error(self.name)
+
+    def normalize_usage(self, raw) -> dict[str, int]:
+        return {}
+
+
+# Registry order is also the order alternatives are suggested in errors.
+PROVIDERS: dict[str, type[Provider]] = {
+    "openai": OpenAIProvider,
+    "anthropic": AnthropicProvider,
+    "google": GoogleProvider,
+    "openrouter": OpenRouterProvider,
+}
+
+
+def unsupported_tools_error(name: str) -> ValueError:
+    """The configure-time error for a provider that declares no tool support."""
+    capable = [n for n, cls in PROVIDERS.items() if cls.supports_tools]
+    alternatives = ", ".join(f"'{n}'" for n in capable[:-1]) + f", or '{capable[-1]}'"
+    return ValueError(
+        f"The '{name}' provider does not yet support tool use, which dacli requires. "
+        f"Use {alternatives}."
+    )
+
+
+def create_provider(name: str, settings: Settings, *, retry) -> Provider:
+    """Instantiate the provider registered under ``name`` (already lowercased)."""
+    cls = PROVIDERS.get(name)
+    if cls is None:
+        raise ValueError(f"Unsupported LLM provider: {name}")
+    return cls(settings, retry=retry)

dacli_ai-0.4.0/src/dacli/ai/scripted.py

@@ -0,0 +1,79 @@
+"""Deterministic, offline stand-in for :class:`reasoning.llm.LLMClient`.
+
+Driven by an ordered list of scripted *responses*; each ``generate()`` call pops
+the next one and returns it in the exact shape the kernel parses
+(``core/kernel.py``): ``(content, tool_calls)`` where each tool call is
+``{"id", "name", "arguments"}``. An empty ``tool_calls`` ends the agent loop
+(final answer). Running past the end raises :class:`ScriptExhausted` — a real
+signal that the agent looped more than the scenario anticipated.
+
+A scripted response is a dict::
+
+    {
+      "text": "optional assistant text",
+      "tool_calls": [ {"name": "update_plan", "arguments": {...}} ],  # optional
+      "usage": {"input": 100, "output": 20},                          # optional
+    }
+"""
+
+from __future__ import annotations
+
+from typing import Any
+import contextlib
+
+
+class ScriptExhausted(RuntimeError):
+    """Raised when ``generate()`` is called after the script is exhausted."""
+
+
+class ScriptedLLM:
+    """An offline LLM double satisfying the kernel's LLM contract."""
+
+    def __init__(self, responses: list[dict[str, Any]]):
+        self._responses: list[dict[str, Any]] = list(responses or [])
+        self._i = 0
+        #: Provider-normalized usage of the most recent generate() call.
+        self.last_usage: dict[str, int] = {}
+        self.exhausted: bool = False
+
+    async def initialize(self) -> None:
+        # No network, nothing to set up.
+        return None
+
+    async def generate(
+        self,
+        messages: list[dict[str, Any]] | None = None,
+        tools: list[dict[str, Any]] | None = None,
+        system_prompt: str | None = None,
+        on_text: Any | None = None,
+        model: str | None = None,
+    ) -> tuple[str, list[dict[str, Any]]]:
+        if self._i >= len(self._responses):
+            self.exhausted = True
+            raise ScriptExhausted(
+                f"ScriptedLLM exhausted after {len(self._responses)} response(s): "
+                "the agent requested another generation the scenario did not script."
+            )
+        spec = self._responses[self._i]
+        self._i += 1
+
+        text = spec.get("text") or ""
+        self.last_usage = dict(spec.get("usage") or {})
+
+        tool_calls: list[dict[str, Any]] = []
+        for j, tc in enumerate(spec.get("tool_calls") or [], start=1):
+            tool_calls.append(
+                {
+                    "id": tc.get("id") or f"call_{self._i}_{j}",
+                    "name": tc["name"],
+                    "arguments": tc.get("arguments") or {},
+                }
+            )
+
+        # Presentation parity with streaming providers (headless on_text is a
+        # no-op; the chat UI streams). Never let a presentation hook break us.
+        if on_text and text:
+            with contextlib.suppress(Exception):
+                on_text(text)
+
+        return text, tool_calls

dacli_ai-0.4.0/src/dacli_ai.egg-info/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: dacli-ai
+Version: 0.4.0
+Summary: Provider LLM client and token/pricing accounting for dacli
+Author-email: Mouad Jaouhari <github@mj-dev.net>
+Project-URL: Homepage, https://github.com/mouadja02/dacli
+Keywords: llm,anthropic,openai,token accounting
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic<1,>=0.40
+Requires-Dist: openai<3,>=1.40
+Requires-Dist: httpx<1,>=0.27
+
+# dacli-ai
+
+Provider LLM client (anthropic / openai / openrouter) and token/pricing accounting
+for [dacli](https://github.com/mouadja02/dacli). The leaf wheel — no dacli-core
+dependency. Embed it with `dacli-core` for a headless agent.

dacli_ai-0.4.0/src/dacli_ai.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/dacli/ai/__init__.py
+src/dacli/ai/llm.py
+src/dacli/ai/pricing.py
+src/dacli/ai/providers.py
+src/dacli/ai/scripted.py
+src/dacli_ai.egg-info/PKG-INFO
+src/dacli_ai.egg-info/SOURCES.txt
+src/dacli_ai.egg-info/dependency_links.txt
+src/dacli_ai.egg-info/requires.txt
+src/dacli_ai.egg-info/top_level.txt

dacli_ai-0.4.0/src/dacli_ai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dacli_ai-0.4.0/src/dacli_ai.egg-info/requires.txt

@@ -0,0 +1,3 @@
+anthropic<1,>=0.40
+openai<3,>=1.40
+httpx<1,>=0.27

dacli_ai-0.4.0/src/dacli_ai.egg-info/top_level.txt

@@ -0,0 +1 @@
+dacli