prompture 0.0.29.dev8__py3-none-any.whl → 0.0.38.dev2__py3-none-any.whl

prompture/logging.py

@@ -0,0 +1,80 @@
+"""Logging configuration for the Prompture library.
+
+Provides a structured JSON formatter and a convenience function for users
+to enable Prompture's internal logging with a single call.
+
+Usage::
+
+    from prompture import configure_logging
+    import logging
+
+    # Simple: enable DEBUG-level output to stderr
+    configure_logging(logging.DEBUG)
+
+    # Structured JSON lines (useful for log aggregation)
+    configure_logging(logging.DEBUG, json_format=True)
+
+    # Provide your own handler
+    fh = logging.FileHandler("prompture.log")
+    configure_logging(logging.INFO, handler=fh)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+
+class JSONFormatter(logging.Formatter):
+    """Emit each log record as a single JSON line.
+
+    Fields always present: ``timestamp``, ``level``, ``logger``, ``message``.
+    If the caller passes ``extra={"prompture_data": ...}`` the value is
+    included under the ``data`` key.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "timestamp": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        data = getattr(record, "prompture_data", None)
+        if data is not None:
+            payload["data"] = data
+        return json.dumps(payload, default=str, ensure_ascii=False)
+
+
+def configure_logging(
+    level: int = logging.DEBUG,
+    handler: logging.Handler | None = None,
+    json_format: bool = False,
+) -> None:
+    """Set up Prompture's library logger for application-level visibility.
+
+    Args:
+        level: Minimum severity to emit (e.g. ``logging.DEBUG``).
+        handler: Custom :class:`logging.Handler`.  When *None*, a
+            :class:`logging.StreamHandler` writing to *stderr* is created.
+        json_format: When *True*, messages are formatted as JSON lines
+            via :class:`JSONFormatter`.
+    """
+    logger = logging.getLogger("prompture")
+    logger.setLevel(level)
+
+    if handler is None:
+        handler = logging.StreamHandler()
+
+    if json_format:
+        handler.setFormatter(JSONFormatter())
+    else:
+        handler.setFormatter(logging.Formatter("%(asctime)s %(name)s %(levelname)s %(message)s"))
+
+    handler.setLevel(level)
+
+    # Avoid adding duplicate handlers when called multiple times.
+    logger.handlers = [h for h in logger.handlers if h is not handler]
+    logger.addHandler(handler)

prompture/model_rates.py

@@ -0,0 +1,217 @@
+"""Live model rates from models.dev API with local caching.
+
+Fetches pricing and metadata for LLM models from https://models.dev/api.json,
+caches locally with TTL-based auto-refresh, and provides lookup functions
+used by drivers for cost calculations.
+"""
+
+import contextlib
+import json
+import logging
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# Maps prompture provider names to models.dev provider names
+PROVIDER_MAP: dict[str, str] = {
+    "openai": "openai",
+    "claude": "anthropic",
+    "google": "google",
+    "groq": "groq",
+    "grok": "xai",
+    "azure": "azure",
+    "openrouter": "openrouter",
+}
+
+_API_URL = "https://models.dev/api.json"
+_CACHE_DIR = Path.home() / ".prompture" / "cache"
+_CACHE_FILE = _CACHE_DIR / "models_dev.json"
+_META_FILE = _CACHE_DIR / "models_dev_meta.json"
+
+_lock = threading.Lock()
+_data: Optional[dict[str, Any]] = None
+_loaded = False
+
+
+def _get_ttl_days() -> int:
+    """Get TTL from settings if available, otherwise default to 7."""
+    try:
+        from .settings import settings
+
+        return getattr(settings, "model_rates_ttl_days", 7)
+    except Exception:
+        return 7
+
+
+def _cache_is_valid() -> bool:
+    """Check whether the local cache exists and is within TTL."""
+    if not _CACHE_FILE.exists() or not _META_FILE.exists():
+        return False
+    try:
+        meta = json.loads(_META_FILE.read_text(encoding="utf-8"))
+        fetched_at = datetime.fromisoformat(meta["fetched_at"])
+        ttl_days = meta.get("ttl_days", _get_ttl_days())
+        age = datetime.now(timezone.utc) - fetched_at
+        return age.total_seconds() < ttl_days * 86400
+    except Exception:
+        return False
+
+
+def _write_cache(data: dict[str, Any]) -> None:
+    """Write API data and metadata to local cache."""
+    try:
+        _CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        _CACHE_FILE.write_text(json.dumps(data), encoding="utf-8")
+        meta = {
+            "fetched_at": datetime.now(timezone.utc).isoformat(),
+            "ttl_days": _get_ttl_days(),
+        }
+        _META_FILE.write_text(json.dumps(meta), encoding="utf-8")
+    except Exception as exc:
+        logger.debug("Failed to write model rates cache: %s", exc)
+
+
+def _read_cache() -> Optional[dict[str, Any]]:
+    """Read cached API data from disk."""
+    try:
+        return json.loads(_CACHE_FILE.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def _fetch_from_api() -> Optional[dict[str, Any]]:
+    """Fetch fresh data from models.dev API."""
+    try:
+        import requests
+
+        resp = requests.get(_API_URL, timeout=15)
+        resp.raise_for_status()
+        return resp.json()
+    except Exception as exc:
+        logger.debug("Failed to fetch model rates from %s: %s", _API_URL, exc)
+        return None
+
+
+def _ensure_loaded() -> Optional[dict[str, Any]]:
+    """Lazy-load data: use cache if valid, otherwise fetch from API."""
+    global _data, _loaded
+    if _loaded:
+        return _data
+
+    with _lock:
+        # Double-check after acquiring lock
+        if _loaded:
+            return _data
+
+        if _cache_is_valid():
+            _data = _read_cache()
+            if _data is not None:
+                _loaded = True
+                return _data
+
+        # Cache missing or expired — fetch fresh
+        fresh = _fetch_from_api()
+        if fresh is not None:
+            _data = fresh
+            _write_cache(fresh)
+        else:
+            # Fetch failed — try stale cache as last resort
+            _data = _read_cache()
+
+        _loaded = True
+        return _data
+
+
+def _lookup_model(provider: str, model_id: str) -> Optional[dict[str, Any]]:
+    """Find a model entry in the cached data.
+
+    The API structure is ``{provider: {model_id: {...}, ...}, ...}``.
+    """
+    data = _ensure_loaded()
+    if data is None:
+        return None
+
+    api_provider = PROVIDER_MAP.get(provider, provider)
+    provider_data = data.get(api_provider)
+    if not isinstance(provider_data, dict):
+        return None
+
+    return provider_data.get(model_id)
+
+
+# ── Public API ──────────────────────────────────────────────────────────────
+
+
+def get_model_rates(provider: str, model_id: str) -> Optional[dict[str, float]]:
+    """Return pricing dict for a model, or ``None`` if unavailable.
+
+    Returned keys mirror models.dev cost fields (per 1M tokens):
+    ``input``, ``output``, and optionally ``cache_read``, ``cache_write``,
+    ``reasoning``.
+    """
+    entry = _lookup_model(provider, model_id)
+    if entry is None:
+        return None
+
+    cost = entry.get("cost")
+    if not isinstance(cost, dict):
+        return None
+
+    rates: dict[str, float] = {}
+    for key in ("input", "output", "cache_read", "cache_write", "reasoning"):
+        val = cost.get(key)
+        if val is not None:
+            with contextlib.suppress(TypeError, ValueError):
+                rates[key] = float(val)
+
+    # Must have at least input and output to be useful
+    if "input" in rates and "output" in rates:
+        return rates
+    return None
+
+
+def get_model_info(provider: str, model_id: str) -> Optional[dict[str, Any]]:
+    """Return full model metadata (cost, limits, capabilities), or ``None``."""
+    return _lookup_model(provider, model_id)
+
+
+def get_all_provider_models(provider: str) -> list[str]:
+    """Return list of model IDs available for a provider."""
+    data = _ensure_loaded()
+    if data is None:
+        return []
+
+    api_provider = PROVIDER_MAP.get(provider, provider)
+    provider_data = data.get(api_provider)
+    if not isinstance(provider_data, dict):
+        return []
+
+    return list(provider_data.keys())
+
+
+def refresh_rates_cache(force: bool = False) -> bool:
+    """Fetch fresh data from models.dev.
+
+    Args:
+        force: If ``True``, fetch even when the cache is still within TTL.
+
+    Returns:
+        ``True`` if fresh data was fetched and cached successfully.
+    """
+    global _data, _loaded
+
+    with _lock:
+        if not force and _cache_is_valid():
+            return False
+
+        fresh = _fetch_from_api()
+        if fresh is not None:
+            _data = fresh
+            _write_cache(fresh)
+            _loaded = True
+            return True
+
+        return False

prompture/persistence.py

@@ -0,0 +1,254 @@
+"""Conversation persistence — file and SQLite storage backends.
+
+Provides:
+
+- :func:`save_to_file` / :func:`load_from_file` for simple JSON file storage.
+- :class:`ConversationStore` for SQLite-backed storage with tag search.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+# ------------------------------------------------------------------
+# File-based persistence
+# ------------------------------------------------------------------
+
+
+def save_to_file(data: dict[str, Any], path: str | Path) -> None:
+    """Write a conversation export dict as JSON to *path*.
+
+    Creates parent directories if they don't exist.
+    """
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def load_from_file(path: str | Path) -> dict[str, Any]:
+    """Read a conversation export dict from a JSON file.
+
+    Raises:
+        FileNotFoundError: If *path* does not exist.
+    """
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"Conversation file not found: {p}")
+    return json.loads(p.read_text(encoding="utf-8"))
+
+
+# ------------------------------------------------------------------
+# SQLite-backed ConversationStore
+# ------------------------------------------------------------------
+
+_DEFAULT_DB_DIR = Path.home() / ".prompture" / "conversations"
+_DEFAULT_DB_PATH = _DEFAULT_DB_DIR / "conversations.db"
+
+_SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS conversations (
+    id TEXT PRIMARY KEY,
+    model_name TEXT NOT NULL,
+    data TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    last_active TEXT NOT NULL,
+    turn_count INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS conversation_tags (
+    conversation_id TEXT NOT NULL,
+    tag TEXT NOT NULL,
+    PRIMARY KEY (conversation_id, tag),
+    FOREIGN KEY (conversation_id) REFERENCES conversations(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_tags_tag ON conversation_tags(tag);
+CREATE INDEX IF NOT EXISTS idx_conversations_last_active ON conversations(last_active);
+"""
+
+
+class ConversationStore:
+    """SQLite-backed conversation storage with tag search.
+
+    Thread-safe — uses an internal :class:`threading.Lock` for all
+    database operations (mirrors the pattern used by ``cache.py``).
+
+    Args:
+        db_path: Path to the SQLite database file.  Defaults to
+            ``~/.prompture/conversations/conversations.db``.
+    """
+
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        self._db_path = Path(db_path) if db_path else _DEFAULT_DB_PATH
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+        self._init_db()
+
+    def _init_db(self) -> None:
+        with self._lock:
+            conn = sqlite3.connect(str(self._db_path))
+            try:
+                conn.executescript(_SCHEMA_SQL)
+                conn.commit()
+            finally:
+                conn.close()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(self._db_path))
+        conn.execute("PRAGMA foreign_keys = ON")
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    # ------------------------------------------------------------------ #
+    # CRUD
+    # ------------------------------------------------------------------ #
+
+    def save(self, conversation_id: str, data: dict[str, Any]) -> None:
+        """Upsert a conversation and replace its tags."""
+        meta = data.get("metadata", {})
+        model_name = data.get("model_name", "")
+        created_at = meta.get("created_at", datetime.now(timezone.utc).isoformat())
+        last_active = meta.get("last_active", datetime.now(timezone.utc).isoformat())
+        turn_count = meta.get("turn_count", 0)
+        tags = meta.get("tags", [])
+
+        data_json = json.dumps(data, ensure_ascii=False)
+
+        with self._lock:
+            conn = self._connect()
+            try:
+                conn.execute(
+                    """
+                    INSERT INTO conversations (id, model_name, data, created_at, last_active, turn_count)
+                    VALUES (?, ?, ?, ?, ?, ?)
+                    ON CONFLICT(id) DO UPDATE SET
+                        model_name = excluded.model_name,
+                        data = excluded.data,
+                        last_active = excluded.last_active,
+                        turn_count = excluded.turn_count
+                    """,
+                    (conversation_id, model_name, data_json, created_at, last_active, turn_count),
+                )
+                # Replace tags
+                conn.execute(
+                    "DELETE FROM conversation_tags WHERE conversation_id = ?",
+                    (conversation_id,),
+                )
+                if tags:
+                    conn.executemany(
+                        "INSERT INTO conversation_tags (conversation_id, tag) VALUES (?, ?)",
+                        [(conversation_id, t) for t in tags],
+                    )
+                conn.commit()
+            finally:
+                conn.close()
+
+    def load(self, conversation_id: str) -> dict[str, Any] | None:
+        """Load a conversation by ID.  Returns ``None`` if not found."""
+        with self._lock:
+            conn = self._connect()
+            try:
+                row = conn.execute(
+                    "SELECT data FROM conversations WHERE id = ?",
+                    (conversation_id,),
+                ).fetchone()
+                if row is None:
+                    return None
+                return json.loads(row["data"])
+            finally:
+                conn.close()
+
+    def delete(self, conversation_id: str) -> bool:
+        """Delete a conversation.  Returns *True* if it existed."""
+        with self._lock:
+            conn = self._connect()
+            try:
+                cursor = conn.execute(
+                    "DELETE FROM conversations WHERE id = ?",
+                    (conversation_id,),
+                )
+                conn.commit()
+                return cursor.rowcount > 0
+            finally:
+                conn.close()
+
+    # ------------------------------------------------------------------ #
+    # Search / listing
+    # ------------------------------------------------------------------ #
+
+    def find_by_tag(self, tag: str) -> list[dict[str, Any]]:
+        """Return summary dicts for all conversations with the given tag."""
+        with self._lock:
+            conn = self._connect()
+            try:
+                rows = conn.execute(
+                    """
+                    SELECT c.id, c.model_name, c.created_at, c.last_active, c.turn_count
+                    FROM conversations c
+                    INNER JOIN conversation_tags ct ON c.id = ct.conversation_id
+                    WHERE ct.tag = ?
+                    ORDER BY c.last_active DESC
+                    """,
+                    (tag,),
+                ).fetchall()
+                return [self._row_to_summary(conn, r) for r in rows]
+            finally:
+                conn.close()
+
+    def find_by_id(self, conversation_id: str) -> dict[str, Any] | None:
+        """Return a summary dict (with tags) for a conversation, or ``None``."""
+        with self._lock:
+            conn = self._connect()
+            try:
+                row = conn.execute(
+                    "SELECT id, model_name, created_at, last_active, turn_count FROM conversations WHERE id = ?",
+                    (conversation_id,),
+                ).fetchone()
+                if row is None:
+                    return None
+                return self._row_to_summary(conn, row)
+            finally:
+                conn.close()
+
+    def list_all(self, limit: int = 100, offset: int = 0) -> list[dict[str, Any]]:
+        """Return summary dicts ordered by ``last_active`` descending."""
+        with self._lock:
+            conn = self._connect()
+            try:
+                rows = conn.execute(
+                    """
+                    SELECT id, model_name, created_at, last_active, turn_count
+                    FROM conversations
+                    ORDER BY last_active DESC
+                    LIMIT ? OFFSET ?
+                    """,
+                    (limit, offset),
+                ).fetchall()
+                return [self._row_to_summary(conn, r) for r in rows]
+            finally:
+                conn.close()
+
+    # ------------------------------------------------------------------ #
+    # Internal
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def _row_to_summary(conn: sqlite3.Connection, row: sqlite3.Row) -> dict[str, Any]:
+        """Build a summary dict from a DB row, including tags."""
+        cid = row["id"]
+        tag_rows = conn.execute(
+            "SELECT tag FROM conversation_tags WHERE conversation_id = ?",
+            (cid,),
+        ).fetchall()
+        return {
+            "id": cid,
+            "model_name": row["model_name"],
+            "created_at": row["created_at"],
+            "last_active": row["last_active"],
+            "turn_count": row["turn_count"],
+            "tags": [tr["tag"] for tr in tag_rows],
+        }