forgeoptimizer 1.0.0__py3-none-any.whl

forgecli/memory/__init__.py

@@ -0,0 +1,12 @@
+"""Local memory store and history (SQLite-backed)."""
+
+from forgecli.memory.cache import Cache
+from forgecli.memory.history import HistoryEntry, HistoryRepository
+from forgecli.memory.store import MemoryStore
+
+__all__ = [
+    "Cache",
+    "HistoryEntry",
+    "HistoryRepository",
+    "MemoryStore",
+]

forgecli/memory/cache.py

@@ -0,0 +1,61 @@
+"""Lightweight in-memory cache with optional TTL.
+
+A future iteration can swap this for SQLite-backed or Redis-backed caching
+without affecting call sites.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from threading import RLock
+from typing import Generic, TypeVar
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+@dataclass
+class _Entry(Generic[V]):
+    value: V
+    expires_at: float | None  # epoch seconds, or None for "no expiry"
+
+
+class Cache(Generic[K, V]):
+    """Thread-safe key/value cache supporting optional per-entry TTL."""
+
+    def __init__(self, *, default_ttl: float | None = None) -> None:
+        self._store: dict[K, _Entry[V]] = {}
+        self._default_ttl = default_ttl
+        self._lock = RLock()
+
+    def get(self, key: K) -> V | None:
+        with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            if entry.expires_at is not None and entry.expires_at < time.time():
+                self._store.pop(key, None)
+                return None
+            return entry.value
+
+    def set(self, key: K, value: V, *, ttl: float | None = None) -> None:
+        effective_ttl = self._default_ttl if ttl is None else ttl
+        expires = time.time() + effective_ttl if effective_ttl else None
+        with self._lock:
+            self._store[key] = _Entry(value=value, expires_at=expires)
+
+    def delete(self, key: K) -> None:
+        with self._lock:
+            self._store.pop(key, None)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._store.clear()
+
+    def __contains__(self, key: K) -> bool:
+        return self.get(key) is not None
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._store)

forgecli/memory/history.py

@@ -0,0 +1,138 @@
+"""Append-only history of CLI invocations and AI interactions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from forgecli.memory.store import MemoryStore
+
+
+@dataclass(frozen=True)
+class HistoryEntry:
+    """A single persisted history record."""
+
+    id: int
+    timestamp: datetime
+    command: str
+    provider: str | None
+    model: str | None
+    prompt_tokens: int
+    completion_tokens: int
+    duration_ms: int
+    success: bool
+    error: str | None
+
+
+class HistoryRepository:
+    """Persistence of CLI/AI invocations keyed by time."""
+
+    def __init__(self, store: MemoryStore, *, history_limit: int = 1000) -> None:
+        self._store = store
+        self._limit = history_limit
+        self._ensure_schema()
+
+    def _ensure_schema(self) -> None:
+        self._store.execute(
+            """
+            CREATE TABLE IF NOT EXISTS history (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                ts TEXT NOT NULL,
+                command TEXT NOT NULL,
+                provider TEXT,
+                model TEXT,
+                prompt_tokens INTEGER NOT NULL DEFAULT 0,
+                completion_tokens INTEGER NOT NULL DEFAULT 0,
+                duration_ms INTEGER NOT NULL DEFAULT 0,
+                success INTEGER NOT NULL DEFAULT 1,
+                error TEXT
+            )
+            """
+        )
+        self._store.execute(
+            "CREATE INDEX IF NOT EXISTS idx_history_ts ON history(ts DESC)"
+        )
+
+    def record(
+        self,
+        *,
+        command: str,
+        provider: str | None = None,
+        model: str | None = None,
+        prompt_tokens: int = 0,
+        completion_tokens: int = 0,
+        duration_ms: int = 0,
+        success: bool = True,
+        error: str | None = None,
+    ) -> int:
+        """Insert a new history row and return its id."""
+        cursor = self._store.execute(
+            """
+            INSERT INTO history (
+                ts, command, provider, model,
+                prompt_tokens, completion_tokens,
+                duration_ms, success, error
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                datetime.now(UTC).isoformat(timespec="seconds"),
+                command,
+                provider,
+                model,
+                prompt_tokens,
+                completion_tokens,
+                duration_ms,
+                int(success),
+                error,
+            ),
+        )
+        self._trim()
+        return int(cursor.lastrowid or 0)
+
+    def list_recent(self, limit: int = 50) -> list[HistoryEntry]:
+        """Return the most recent history entries (newest first)."""
+        rows = self._store.execute(
+            """
+            SELECT id, ts, command, provider, model,
+                   prompt_tokens, completion_tokens,
+                   duration_ms, success, error
+            FROM history
+            ORDER BY id DESC
+            LIMIT ?
+            """,
+            (limit,),
+        ).fetchall()
+        return [self._to_entry(r) for r in rows]
+
+    def _trim(self) -> None:
+        """Drop oldest rows past the configured retention limit."""
+        row = self._store.execute("SELECT COUNT(*) AS n FROM history").fetchone()
+        total = int(row["n"]) if row else 0
+        if total <= self._limit:
+            return
+        excess = total - self._limit
+        self._store.execute(
+            """
+            DELETE FROM history
+            WHERE id IN (
+                SELECT id FROM history ORDER BY id ASC LIMIT ?
+            )
+            """,
+            (excess,),
+        )
+
+    @staticmethod
+    def _to_entry(row: Any) -> HistoryEntry:
+        return HistoryEntry(
+            id=int(row["id"]),
+            timestamp=datetime.fromisoformat(row["ts"]),
+            command=str(row["command"]),
+            provider=row["provider"],
+            model=row["model"],
+            prompt_tokens=int(row["prompt_tokens"] or 0),
+            completion_tokens=int(row["completion_tokens"] or 0),
+            duration_ms=int(row["duration_ms"] or 0),
+            success=bool(row["success"]),
+            error=row["error"],
+        )

forgecli/memory/store.py

@@ -0,0 +1,87 @@
+"""SQLite-backed local memory store (singleton lifecycle owned by AppContext)."""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from forgecli.utils.fs import ensure_dir
+
+
+class MemoryStore:
+    """Thin wrapper around a local SQLite database.
+
+    The store is intentionally minimal: it owns the connection and provides
+    a few named-table helpers. Higher-level repositories (e.g. history)
+    layer domain logic on top.
+    """
+
+    SCHEMA_VERSION = 1
+
+    def __init__(self, db_path: Path) -> None:
+        self._db_path = Path(db_path)
+        ensure_dir(self._db_path.parent)
+        self._conn: sqlite3.Connection | None = None
+
+    @property
+    def db_path(self) -> Path:
+        return self._db_path
+
+    def connect(self) -> None:
+        """Open the database and run schema migrations."""
+        if self._conn is not None:
+            return
+        self._conn = sqlite3.connect(
+            str(self._db_path),
+            check_same_thread=False,
+            isolation_level=None,  # autocommit; we use explicit transactions
+        )
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode = WAL")
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._migrate()
+
+    def close(self) -> None:
+        """Close the underlying connection if open."""
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None
+
+    def __enter__(self) -> MemoryStore:
+        self.connect()
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    @property
+    def conn(self) -> sqlite3.Connection:
+        if self._conn is None:
+            raise RuntimeError("MemoryStore.connect() must be called first")
+        return self._conn
+
+    def _migrate(self) -> None:
+        self.conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS schema_meta (
+                key TEXT PRIMARY KEY,
+                value TEXT NOT NULL
+            )
+            """
+        )
+        row = self.conn.execute(
+            "SELECT value FROM schema_meta WHERE key = 'version'"
+        ).fetchone()
+        if row is None:
+            self.conn.execute(
+                "INSERT INTO schema_meta (key, value) VALUES ('version', ?)",
+                (str(self.SCHEMA_VERSION),),
+            )
+        # Future migrations can be chained here by inspecting ``row``.
+
+    def execute(self, sql: str, params: tuple[Any, ...] = ()) -> sqlite3.Cursor:
+        return self.conn.execute(sql, params)
+
+    def executemany(self, sql: str, params: list[tuple[Any, ...]]) -> sqlite3.Cursor:
+        return self.conn.executemany(sql, params)

forgecli/optimizer/__init__.py

@@ -0,0 +1,14 @@
+"""Context optimization: chunking, ranking, summarization, token optimization."""
+
+from forgecli.optimizer.chunker import Chunker
+from forgecli.optimizer.optimizer import ContextOptimizer
+from forgecli.optimizer.ranker import Ranker
+from forgecli.optimizer.summarizer import Summarizer
+
+__all__ = [
+    "Chunker",
+    "ContextOptimizer",
+    "Ranker",
+    "Summarizer",
+]
+

forgecli/optimizer/caveman/__init__.py

@@ -0,0 +1,173 @@
+"""Caveman token-optimizer integration.
+
+Caveman is a prompt-level optimization technique that reduces LLM output
+tokens by ~65% on average. It works by injecting a system prompt that
+tells the model to communicate in a compressed, token-efficient style —
+dropping filler words, pleasantries, and using fragments — while keeping
+all technical terms exact.
+
+Two implementations are shipped:
+
+* :class:`CavemanRulesetOptimizer` — a self-contained Python
+  implementation of the Caveman ruleset (lite / full / ultra / wenyan).
+  Always available, no external dependencies.
+* :class:`CavemanCLIOptimizer` — an optional adapter that shells out
+  to an external ``caveman`` binary if one is on ``PATH``.
+
+The :class:`CavemanCompositeOptimizer` picks between them at runtime.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from enum import Enum
+
+from forgecli.optimizer.ponytail import OptimizedRequest
+from forgecli.providers.base import ChatMessage, ChatRequest
+
+
+class CavemanIntensity(str, Enum):
+    """How aggressively to compress LLM output.
+
+    * ``off``    - no rewriting; pass prompts through unchanged.
+    * ``lite``   - be concise; drop filler words and pleasantries.
+    * ``full``   - full caveman: fragments, [thing][action][reason] pattern.
+    * ``ultra``  - maximum compression; grunt-level communication.
+    * ``wenyan`` - Classical Chinese literary style (文言) for max density.
+    """
+
+    OFF = "off"
+    LITE = "lite"
+    FULL = "full"
+    ULTRA = "ultra"
+    WENYAN = "wenyan"
+
+    @classmethod
+    def parse(cls, value: str | CavemanIntensity | None) -> CavemanIntensity:
+        """Parse a string into an :class:`CavemanIntensity`, falling back to LITE."""
+        if value is None or value == "":
+            return cls.LITE
+        if isinstance(value, cls):
+            return value
+        try:
+            return cls(value.lower())
+        except ValueError as exc:
+            raise ValueError(
+                f"Unknown caveman intensity {value!r}; expected one of "
+                f"{', '.join(i.value for i in cls)}"
+            ) from exc
+
+
+class CavemanPromptOptimizer(ABC):
+    """Strategy interface for Caveman prompt optimization.
+
+    Implementations must be deterministic and side-effect free
+    (other than logging), so they can be invoked transparently before
+    every model call.
+    """
+
+    name: str = "abstract-caveman"
+
+    @abstractmethod
+    async def optimize_chat(
+        self, request: ChatRequest
+    ) -> OptimizedRequest:
+        """Return an optimized copy of ``request``."""
+
+    async def is_available(self) -> bool:
+        """Return whether this optimizer is available to use."""
+        return True
+
+
+class CavemanCompositeOptimizer(CavemanPromptOptimizer):
+    """Pick the right optimizer for the configured :class:`CavemanIntensity`."""
+
+    name = "caveman-composite"
+
+    def __init__(
+        self,
+        *,
+        intensity: CavemanIntensity = CavemanIntensity.LITE,
+        ruleset: CavemanPromptOptimizer | None = None,
+        external: CavemanPromptOptimizer | None = None,
+    ) -> None:
+        self._intensity = intensity
+        self._ruleset = ruleset
+        self._external = external
+        self._sync_ruleset_intensity()
+
+    def _sync_ruleset_intensity(self) -> None:
+        """Propagate the composite's intensity to the ruleset, if compatible."""
+        ruleset = self._ruleset
+        if isinstance(ruleset, CavemanRulesetOptimizer):
+            ruleset.set_intensity(self._intensity)
+
+    @property
+    def intensity(self) -> CavemanIntensity:
+        return self._intensity
+
+    def set_intensity(self, intensity: CavemanIntensity | str) -> None:
+        self._intensity = CavemanIntensity.parse(intensity)
+        if isinstance(self._ruleset, CavemanRulesetOptimizer):
+            self._ruleset.set_intensity(self._intensity)
+
+    async def optimize_chat(self, request: ChatRequest) -> OptimizedRequest:
+        if self._intensity is CavemanIntensity.OFF:
+            return OptimizedRequest(
+                request=request,
+                notes=("caveman off",),
+                intensity=self._intensity,
+                source="caveman-passthrough",
+            )
+
+        if self._external is not None and await self._external.is_available():
+            result = await self._external.optimize_chat(request)
+            return OptimizedRequest(
+                request=result.request,
+                notes=(*result.notes, "caveman external"),
+                intensity=self._intensity,
+                source="caveman-external",
+            )
+
+        if self._ruleset is None:
+            return OptimizedRequest(
+                request=request,
+                notes=("no caveman ruleset registered",),
+                intensity=self._intensity,
+                source="caveman-passthrough",
+            )
+
+        result = await self._ruleset.optimize_chat(request)
+        return OptimizedRequest(
+            request=result.request,
+            notes=result.notes,
+            intensity=self._intensity,
+            source="caveman-ruleset",
+        )
+
+
+def _ensure_user_message(messages: Sequence[ChatMessage]) -> bool:
+    return any(m.role.value == "user" for m in messages)
+
+
+def _clone_request(
+    request: ChatRequest, messages: Sequence[ChatMessage]
+) -> ChatRequest:
+    """Return a copy of ``request`` with ``messages`` replaced."""
+    return request.model_copy(update={"messages": list(messages)})
+
+
+__all__ = [
+    "CavemanCLIOptimizer",
+    "CavemanCompositeOptimizer",
+    "CavemanIntensity",
+    "CavemanPromptOptimizer",
+    "CavemanProvider",
+    "CavemanRulesetOptimizer",
+    "OptimizedRequest",
+]
+
+from forgecli.optimizer.caveman.cli import CavemanCLIOptimizer  # noqa: E402
+from forgecli.optimizer.caveman.decorator import CavemanProvider  # noqa: E402
+from forgecli.optimizer.caveman.ruleset import CavemanRulesetOptimizer  # noqa: E402

forgecli/optimizer/caveman/cli.py

@@ -0,0 +1,64 @@
+"""Optional adapter that shells out to an external ``caveman`` binary.
+
+The external binary is **not** shipped with ForgeCLI. The adapter
+is here so the :class:`CavemanCompositeOptimizer` can transparently
+pick it when the user has installed a caveman CLI tool separately.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+
+from forgecli.optimizer.caveman import (
+    CavemanIntensity,
+    CavemanPromptOptimizer,
+    OptimizedRequest,
+)
+from forgecli.providers.base import ChatRequest
+
+_log = logging.getLogger("forgecli.optimizer.caveman.cli")
+
+
+class CavemanCLIOptimizer(CavemanPromptOptimizer):
+    """Shell out to an external ``caveman`` binary for prompt optimization."""
+
+    name = "caveman.cli"
+
+    def __init__(
+        self,
+        executable: str = "caveman",
+        timeout_seconds: float = 30.0,
+    ) -> None:
+        self._executable = executable
+        self._timeout = timeout_seconds
+
+    async def is_available(self) -> bool:
+        """Return True when the ``caveman`` binary is on ``PATH``."""
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None, lambda: shutil.which(self._executable) is not None
+        )
+
+    async def optimize_chat(self, request: ChatRequest) -> OptimizedRequest:
+        """Run the external caveman binary and return the optimized request.
+
+        Currently a stub that returns the request unchanged \u2014 the
+        caveman CLI protocol hasn't been standardised yet. Implement
+        this method once a stable CLI interface exists.
+        """
+        _log.debug(
+            "caveman CLI adapter called; binary=%s available=%s",
+            self._executable,
+            await self.is_available(),
+        )
+        return OptimizedRequest(
+            request=request,
+            notes=("caveman CLI stub (passthrough)",),
+            intensity=CavemanIntensity.LITE,
+            source="caveman-cli",
+        )
+
+
+__all__ = ["CavemanCLIOptimizer"]

forgecli/optimizer/caveman/decorator.py

@@ -0,0 +1,67 @@
+"""A :class:`Provider` decorator that runs a :class:`CavemanPromptOptimizer`
+on every chat request before delegating to the wrapped provider.
+
+The decorator is transparent for every other operation (``stream``,
+``embed``, ``list_models``) \u2014 those either pass through unchanged or
+inherit the base behaviour.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from forgecli.optimizer.caveman import CavemanPromptOptimizer, OptimizedRequest
+from forgecli.providers.base import (
+    ChatRequest,
+    ChatResponse,
+    EmbeddingRequest,
+    EmbeddingResponse,
+    ModelInfo,
+    Provider,
+    StreamChunk,
+)
+
+
+class CavemanProvider(Provider[Any]):
+    """Wrap a :class:`Provider` so every chat call is caveman-optimized."""
+
+    name = "caveman-provider"
+
+    def __init__(
+        self,
+        base: Provider[Any],
+        optimizer: CavemanPromptOptimizer,
+    ) -> None:
+        super().__init__(base.config)
+        self._base = base
+        self._optimizer = optimizer
+
+    @property
+    def base(self) -> Provider[Any]:
+        return self._base
+
+    @property
+    def optimizer(self) -> CavemanPromptOptimizer:
+        return self._optimizer
+
+    async def chat(self, request: ChatRequest) -> ChatResponse:
+        optimized: OptimizedRequest = await self._optimizer.optimize_chat(request)
+        return await self._base.chat(optimized.request)
+
+    async def stream(self, request: ChatRequest) -> AsyncIterator[StreamChunk]:
+        optimized: OptimizedRequest = await self._optimizer.optimize_chat(request)
+        async for chunk in self._base.stream(optimized.request):
+            yield chunk
+
+    async def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        return await self._base.embed(request)
+
+    async def list_models(self) -> list[ModelInfo]:
+        return await self._base.list_models()
+
+    def validate(self) -> None:
+        return self._base.validate()
+
+
+__all__ = ["CavemanProvider"]

forgecli/optimizer/caveman/factory.py

@@ -0,0 +1,51 @@
+"""Factory for building the live :class:`CavemanPromptOptimizer`."""
+
+from __future__ import annotations
+
+from forgecli.config.settings import ForgeSettings
+from forgecli.optimizer.caveman import (
+    CavemanCLIOptimizer,
+    CavemanCompositeOptimizer,
+    CavemanIntensity,
+    CavemanPromptOptimizer,
+    CavemanRulesetOptimizer,
+)
+from forgecli.optimizer.caveman.state import CavemanState
+
+
+def build_caveman_optimizer(
+    state: CavemanState,
+    settings: ForgeSettings | None = None,
+) -> CavemanPromptOptimizer:
+    """Build the composite Caveman optimizer from runtime state + config.
+
+    The composite always falls back to the in-process ruleset; the
+    external CLI adapter is added on top whenever the configured
+    backend asks for it and the binary is available.
+    """
+    ruleset = CavemanRulesetOptimizer(intensity=state.intensity)
+
+    external: CavemanPromptOptimizer | None = None
+    if state.backend in {"cli", "auto"}:
+        binary = state.binary
+        if settings is not None and settings.caveman.binary:
+            binary = settings.caveman.binary
+        external = CavemanCLIOptimizer(executable=binary)
+    elif state.backend == "ruleset":
+        external = None
+
+    if settings is not None and not settings.caveman.enabled:
+        return CavemanCompositeOptimizer(
+            intensity=CavemanIntensity.OFF,
+            ruleset=ruleset,
+            external=external,
+        )
+
+    return CavemanCompositeOptimizer(
+        intensity=state.intensity,
+        ruleset=ruleset,
+        external=external,
+    )
+
+
+__all__ = ["build_caveman_optimizer"]