forgeoptimizer 1.0.0__py3-none-any.whl

forgecli/optimizer/caveman/ruleset.py

@@ -0,0 +1,156 @@
+"""Self-contained Python implementation of the Caveman ruleset.
+
+The ruleset mirrors the behavior described on https://github.com/JuliusBrussee/caveman.
+It does not shell out to anything; it rewrites the system message of a
+:class:`ChatRequest` to bias the model toward token-efficient output.
+
+The five intensity levels match the official Caveman project:
+
+* ``off``    - pass-through (handled by the composite, not this class).
+* ``lite``   - concise communication; 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 semantic density.
+
+The output is deterministic for a given (intensity, prompt) pair, so
+tests can pin it.
+"""
+
+from __future__ import annotations
+
+from forgecli.optimizer.caveman import (
+    CavemanIntensity,
+    CavemanPromptOptimizer,
+    OptimizedRequest,
+    _clone_request,
+    _ensure_user_message,
+)
+from forgecli.providers.base import ChatMessage, ChatRequest, Role
+
+_CAVEMAN_GUIDANCE: dict[CavemanIntensity, str] = {
+    CavemanIntensity.OFF: "",
+    CavemanIntensity.LITE: (
+        "CAVEMAN (lite): communicate concisely. "
+        "Drop filler words (just, really, basically, actually). "
+        "Drop pleasantries (sure, certainly, happy to, I think). "
+        "Use short sentences. Keep technical terms exact."
+    ),
+    CavemanIntensity.FULL: (
+        "CAVEMAN (full): talk like caveman. Brain still big, mouth small.\n\n"
+        "Rules:\n"
+        "- Drop filler words, pleasantries, transition phrases\n"
+        "- Use sentence fragments where meaning is clear\n"
+        "- Keep technical terms exact \u2014 never simplify them\n"
+        "- Follow [thing] [action] [reason] pattern\n"
+        "- No summaries, no disclaimers, no meta-commentary\n"
+        "- Code blocks and error messages stay unmodified"
+    ),
+    CavemanIntensity.ULTRA: (
+        "CAVEMAN (ultra): maximum compression.\n\n"
+        "- One sentence max per idea\n"
+        "- No articles (a, an, the) unless essential\n"
+        "- No polite prefixes \u2014 get straight to the point\n"
+        "- [action] [thing] directly\n"
+        "- Grunt-level communication preferred\n"
+        "- Code unchanged. Technical terms unchanged."
+    ),
+    CavemanIntensity.WENYAN: (
+        "CAVEMAN (wenyan): respond in Classical Chinese literary style "
+        "(\u6587\u8a00 / wenyanwen).\n\n"
+        "- Maximum semantic density per character\n"
+        "- Use classical parallel structure where appropriate\n"
+        "- Eliminate all modern conversational padding\n"
+        "- \u4e00\u8a00\u4ee5\u84cb\u4e4b: express essence in minimum characters\n"
+        "- Code blocks, technical terms, and proper nouns stay in original form"
+    ),
+}
+
+
+class CavemanRulesetOptimizer(CavemanPromptOptimizer):
+    """Rewrite system messages to apply the Caveman ruleset."""
+
+    name = "caveman.ruleset"
+
+    def __init__(self, *, intensity: CavemanIntensity = CavemanIntensity.LITE) -> None:
+        self._intensity = CavemanIntensity.parse(intensity)
+
+    @property
+    def intensity(self) -> CavemanIntensity:
+        return self._intensity
+
+    def set_intensity(self, intensity: CavemanIntensity | str) -> None:
+        self._intensity = CavemanIntensity.parse(intensity)
+
+    async def optimize_chat(self, request: ChatRequest) -> OptimizedRequest:
+        if self._intensity is CavemanIntensity.OFF:
+            return OptimizedRequest(
+                request=request,
+                notes=("caveman off",),
+                intensity=CavemanIntensity.OFF,
+                source="caveman-ruleset",
+            )
+
+        guidance = _CAVEMAN_GUIDANCE[self._intensity]
+        messages = list(request.messages)
+
+        if not _ensure_user_message(messages):
+            return OptimizedRequest(
+                request=request,
+                notes=("no user message; caveman passthrough",),
+                intensity=self._intensity,
+                source="caveman-ruleset",
+            )
+
+        rewritten = _rewrite_messages(messages, guidance)
+        notes = _build_notes(self._intensity)
+        return OptimizedRequest(
+            request=_clone_request(request, rewritten),
+            notes=notes,
+            intensity=self._intensity,
+            source="caveman-ruleset",
+        )
+
+
+def _rewrite_messages(
+    messages: list[ChatMessage],
+    guidance: str,
+) -> list[ChatMessage]:
+    """Insert Caveman guidance at the head of the conversation.
+
+    Rules:
+    * If the first message is a system message, prepend the guidance
+      to it (separated by two newlines).
+    * If there is no system message, insert one.
+    * If the first system message is *empty*, replace it.
+    * Otherwise the user/assistant turns are left untouched.
+    """
+    if not messages:
+        return [ChatMessage(role=Role.SYSTEM, content=guidance)]
+
+    first = messages[0]
+    if first.role is Role.SYSTEM:
+        existing = first.content.strip()
+        if not existing:
+            return [ChatMessage(role=Role.SYSTEM, content=guidance), *messages[1:]]
+        new_content = f"{guidance}\n\n{first.content}" if guidance else first.content
+        return [ChatMessage(role=Role.SYSTEM, content=new_content), *messages[1:]]
+
+    return [ChatMessage(role=Role.SYSTEM, content=guidance), *messages]
+
+
+def _build_notes(intensity: CavemanIntensity) -> tuple[str, ...]:
+    notes: list[str] = [f"caveman intensity={intensity.value}"]
+    if intensity is CavemanIntensity.FULL:
+        notes.append("caveman full mode \u2014 fragments + [thing][action][reason]")
+    elif intensity is CavemanIntensity.ULTRA:
+        notes.append("caveman ultra \u2014 maximum compression")
+    elif intensity is CavemanIntensity.WENYAN:
+        notes.append("caveman wenyan \u2014 classical Chinese literary style")
+    elif intensity is CavemanIntensity.LITE:
+        notes.append("caveman lite \u2014 concise, no filler")
+    return tuple(notes)
+
+
+__all__ = [
+    "CavemanRulesetOptimizer",
+]

forgecli/optimizer/caveman/state.py

@@ -0,0 +1,52 @@
+"""Live runtime state for the Caveman optimizer.
+
+The intensity can be flipped at runtime. Because the setting is held
+in :class:`AppContext.extras`, every subcommand that resolves the
+optimizer sees the latest value. Tests can override it directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from forgecli.optimizer.caveman import CavemanIntensity
+
+
+@dataclass
+class CavemanState:
+    """Mutable intensity for the running CLI process."""
+
+    intensity: CavemanIntensity = CavemanIntensity.LITE
+    backend: str = "ruleset"  # "ruleset" | "cli" | "auto"
+    binary: str = "caveman"
+
+    @classmethod
+    def from_extras(cls, extras: dict[str, object]) -> CavemanState:
+        state = cls()
+        intensity = extras.get("caveman.intensity") or extras.get(
+            "caveman_intensity"
+        )
+        backend = extras.get("caveman.backend") or extras.get("caveman_backend")
+        binary = extras.get("caveman.binary") or extras.get("caveman_binary")
+        if isinstance(intensity, str):
+            try:
+                state.intensity = CavemanIntensity.parse(intensity)
+            except ValueError:
+                state.intensity = CavemanIntensity.LITE
+        elif isinstance(intensity, CavemanIntensity):
+            state.intensity = intensity
+        if isinstance(backend, str):
+            state.backend = backend
+        if isinstance(binary, str):
+            state.binary = binary
+        return state
+
+    def to_extras(self) -> dict[str, str]:
+        return {
+            "caveman.intensity": self.intensity.value,
+            "caveman.backend": self.backend,
+            "caveman.binary": self.binary,
+        }
+
+
+__all__ = ["CavemanState"]

forgecli/optimizer/chunker.py

@@ -0,0 +1,85 @@
+"""Chunkers split long content into model-sized pieces."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class SupportsLen(Protocol):
+    """Minimal protocol for anything with a ``text`` attribute."""
+
+    text: str
+
+
+@dataclass(frozen=True)
+class Chunk:
+    """A piece of content along with its provenance."""
+
+    text: str
+    index: int
+    start: int
+    end: int
+    source_id: str | None = None
+
+
+class Chunker:
+    """Split text into overlapping windows of ``size`` characters.
+
+    This is intentionally the dumbest possible chunker; smarter chunkers
+    (e.g. AST-aware, sentence-aware) can be added by implementing the
+    same interface and registering them with the optimizer.
+    """
+
+    def __init__(self, *, size: int = 4000, overlap: int = 200) -> None:
+        if size <= 0:
+            raise ValueError("chunk size must be positive")
+        if overlap < 0 or overlap >= size:
+            raise ValueError("overlap must be in [0, size)")
+        self._size = size
+        self._overlap = overlap
+
+    @property
+    def size(self) -> int:
+        return self._size
+
+    @property
+    def overlap(self) -> int:
+        return self._overlap
+
+    def split(self, text: str, *, source_id: str | None = None) -> list[Chunk]:
+        """Split ``text`` into chunks of up to ``self.size`` characters."""
+        if not text:
+            return []
+        chunks: list[Chunk] = []
+        step = self._size - self._overlap
+        idx = 0
+        pos = 0
+        n = len(text)
+        while pos < n:
+            end = min(pos + self._size, n)
+            chunks.append(
+                Chunk(
+                    text=text[pos:end],
+                    index=idx,
+                    start=pos,
+                    end=end,
+                    source_id=source_id,
+                )
+            )
+            idx += 1
+            if end == n:
+                break
+            pos += step
+        return chunks
+
+    def split_many(
+        self,
+        items: Iterable[tuple[str, str | None]],
+    ) -> list[Chunk]:
+        """Split several texts; ``items`` yields ``(text, source_id)`` pairs."""
+        result: list[Chunk] = []
+        for text, source_id in items:
+            result.extend(self.split(text, source_id=source_id))
+        return result

forgecli/optimizer/optimizer.py

@@ -0,0 +1,81 @@
+"""High-level context orchestrator: chunk → rank → (optionally) summarize."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from forgecli.core.service import Service
+from forgecli.optimizer.chunker import Chunk, Chunker
+from forgecli.optimizer.ranker import Ranker
+from forgecli.optimizer.summarizer import Summarizer
+
+
+@dataclass
+class OptimizedContext:
+    """The output of :meth:`ContextOptimizer.optimize`."""
+
+    chunks: list[Chunk] = field(default_factory=list)
+    summary: str = ""
+    total_chars: int = 0
+
+
+class ContextOptimizer(Service):
+    """Orchestrates chunking, ranking, and summarization."""
+
+    name = "optimizer"
+
+    def __init__(
+        self,
+        *,
+        chunker: Chunker | None = None,
+        ranker: Ranker | None = None,
+        summarizer: Summarizer | None = None,
+        max_context_tokens: int = 200_000,
+    ) -> None:
+        super().__init__()
+        self._chunker = chunker or Chunker()
+        self._ranker = ranker or Ranker()
+        self._summarizer = summarizer
+        self._max_tokens = max_context_tokens
+
+    @property
+    def chunker(self) -> Chunker:
+        return self._chunker
+
+    @property
+    def ranker(self) -> Ranker:
+        return self._ranker
+
+    @property
+    def summarizer(self) -> Summarizer | None:
+        return self._summarizer
+
+    def optimize(
+        self,
+        text: str,
+        *,
+        query: str = "",
+        source_id: str | None = None,
+    ) -> OptimizedContext:
+        """Chunk ``text`` and rank it against ``query`` (no AI call)."""
+        chunks = self._chunker.split(text, source_id=source_id)
+        if query:
+            ranked = self._ranker.rank(query, chunks)
+            chunks = [chunk for chunk, _score in ranked]
+        return OptimizedContext(
+            chunks=chunks,
+            total_chars=sum(len(c.text) for c in chunks),
+        )
+
+    async def optimize_and_summarize(
+        self,
+        text: str,
+        *,
+        query: str = "",
+        source_id: str | None = None,
+    ) -> OptimizedContext:
+        """Like :meth:`optimize` but produces a summary when a summarizer is set."""
+        ctx = self.optimize(text, query=query, source_id=source_id)
+        if self._summarizer is not None and ctx.chunks:
+            ctx.summary = await self._summarizer.summarize(ctx.chunks)
+        return ctx

forgecli/optimizer/ponytail/__init__.py

@@ -0,0 +1,183 @@
+"""Ponytail prompt-optimizer integration.
+
+ForgeCLI integrates the [Ponytail](https://ponytail.dev/) ruleset
+behind a small :class:`PromptOptimizer` interface and applies it
+transparently to every chat call. Two implementations are shipped:
+
+* :class:`PonytailRulesetOptimizer` — a self-contained Python
+  implementation of the Ponytail "ladder" (lite / full / ultra).
+  Always available, no external dependencies.
+* :class:`PonytailCLIOptimizer` — an optional adapter that shells out
+  to an external ``ponytail`` binary if one is on ``PATH``.
+
+The :class:`CompositeOptimizer` picks between them at runtime.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import Enum
+
+from forgecli.providers.base import ChatMessage, ChatRequest
+
+
+class Intensity(str, Enum):
+    """How aggressively to optimize prompts.
+
+    The semantics match the Ponytail commands exactly:
+
+    * ``off``   - no rewriting; pass prompts through unchanged.
+    * ``lite``  - default; appends a one-line hint naming the lazier
+                  alternative and lets the model decide.
+    * ``full``  - applies the full "ladder" ruleset and instructs the
+                  model to ship the shortest diff.
+    * ``ultra`` - aggressive YAGNI; instructs the model to challenge
+                  the rest of the requirement in the same breath.
+    """
+
+    OFF = "off"
+    LITE = "lite"
+    FULL = "full"
+    ULTRA = "ultra"
+
+    @classmethod
+    def parse(cls, value: str | Intensity | None) -> Intensity:
+        """Parse a string into an :class:`Intensity`, 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 intensity {value!r}; expected one of "
+                f"{', '.join(i.value for i in cls)}"
+            ) from exc
+
+
+@dataclass(frozen=True)
+class OptimizedRequest:
+    """The output of :meth:`PromptOptimizer.optimize_chat`."""
+
+    request: ChatRequest
+    notes: tuple[str, ...] = ()
+    intensity: Intensity = Intensity.LITE
+    source: str = "ruleset"  # "ruleset" | "external" | "passthrough"
+
+
+class PromptOptimizer(ABC):
+    """Strategy interface for 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"
+
+    @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 CompositeOptimizer(PromptOptimizer):
+    """Pick the right optimizer for the configured :class:`Intensity`."""
+
+    name = "composite"
+
+    def __init__(
+        self,
+        *,
+        intensity: Intensity = Intensity.LITE,
+        ruleset: PromptOptimizer | None = None,
+        external: PromptOptimizer | 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, PonytailRulesetOptimizer):
+            ruleset.set_intensity(self._intensity)
+
+    @property
+    def intensity(self) -> Intensity:
+        return self._intensity
+
+    def set_intensity(self, intensity: Intensity | str) -> None:
+        self._intensity = Intensity.parse(intensity)
+        # Keep the ruleset in sync so its output reflects the new level
+        # when we fall back to it.
+        if isinstance(self._ruleset, PonytailRulesetOptimizer):
+            self._ruleset.set_intensity(self._intensity)
+
+    async def optimize_chat(self, request: ChatRequest) -> OptimizedRequest:
+        if self._intensity is Intensity.OFF:
+            return OptimizedRequest(
+                request=request,
+                notes=("optimizer off",),
+                intensity=Intensity.OFF,
+                source="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,
+                intensity=self._intensity,
+                source="external",
+            )
+
+        if self._ruleset is None:
+            return OptimizedRequest(
+                request=request,
+                notes=("no ruleset registered",),
+                intensity=self._intensity,
+                source="passthrough",
+            )
+
+        result = await self._ruleset.optimize_chat(request)
+        return OptimizedRequest(
+            request=result.request,
+            notes=result.notes,
+            intensity=self._intensity,
+            source="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__ = [
+    "CompositeOptimizer",
+    "Intensity",
+    "OptimizedProvider",
+    "OptimizedRequest",
+    "PonytailCLIOptimizer",
+    "PonytailRulesetOptimizer",
+    "PromptOptimizer",
+]
+
+# Re-export the two concrete implementations and the decorator.
+from forgecli.optimizer.ponytail.cli import PonytailCLIOptimizer  # noqa: E402
+from forgecli.optimizer.ponytail.decorator import OptimizedProvider  # noqa: E402
+from forgecli.optimizer.ponytail.ruleset import PonytailRulesetOptimizer  # noqa: E402