forgeoptimizer 0.1.0__py3-none-any.whl

forgecli/optimizer/caveman/cli.py

@@ -0,0 +1,62 @@
+"""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"]

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,50 @@
+"""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