minima-cli 0.4.9__py3-none-any.whl

minima_harness/ai/stream.py

@@ -0,0 +1,82 @@
+"""Unified generation entry points: ``stream()`` and ``complete()``.
+
+Dispatches to the provider registered for ``model.api``. ``stream()`` returns an async
+iterable that also exposes ``await s.result()`` (mirrors PI's TS stream object).
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+from minima_harness.ai.events import DoneEvent, ErrorEvent, Event
+from minima_harness.ai.providers.base import get_provider
+
+if TYPE_CHECKING:
+    from minima_harness.ai.types import AssistantMessage, Context, Model
+
+
+class Stream:
+    """Async iterator over events with a ``.result()`` helper for the final message."""
+
+    def __init__(self, gen: AsyncIterator[Event]) -> None:
+        self._gen = gen
+        self._result: AssistantMessage | None = None
+        self._consumed = False
+
+    def __aiter__(self) -> Stream:
+        return self
+
+    async def __anext__(self) -> Event:
+        try:
+            event = await self._gen.__anext__()
+        except StopAsyncIteration as exc:
+            self._consumed = True
+            raise exc
+        if isinstance(event, DoneEvent):
+            self._result = event.message
+            self._consumed = True
+        elif isinstance(event, ErrorEvent):
+            self._result = event.error
+            self._consumed = True
+        return event
+
+    async def result(self) -> AssistantMessage:
+        """Drain the stream and return the final assistant message (done or error)."""
+        async for _ in self:
+            pass
+        if self._result is None:  # pragma: no cover - defensive
+            raise RuntimeError("stream ended without a done/error event")
+        return self._result
+
+
+def stream(
+    model: Model,
+    context: Context,
+    *,
+    options: dict[str, Any] | None = None,
+    signal: object | None = None,
+) -> Stream:
+    """Begin streaming a generation for ``model`` against ``context``.
+
+    Returns a :class:`Stream` synchronously (matching PI's TS ``stream()`` which is not
+    a promise); iterate it with ``async for`` and call ``await s.result()`` for the
+    final message.
+    """
+    from minima_harness.ai.providers import ensure_providers_registered
+
+    ensure_providers_registered()
+    provider = get_provider(model.api)
+    return Stream(provider.stream(model, context, options=options, signal=signal))
+
+
+async def complete(
+    model: Model,
+    context: Context,
+    *,
+    options: dict[str, Any] | None = None,
+    signal: object | None = None,
+) -> AssistantMessage:
+    """Non-streaming convenience: return the final assistant message."""
+    s = stream(model, context, options=options, signal=signal)
+    return await s.result()

minima_harness/ai/tools.py

@@ -0,0 +1,51 @@
+"""Tool argument validation — the pydantic analogue of PI's TypeBox ``validateToolCall``.
+
+Tools declare their parameters as a pydantic ``BaseModel`` subclass. The agent loop
+auto-validates before execution; failures are returned to the model as tool errors so it
+can retry (matching PI's behaviour).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ValidationError
+
+from minima_harness.ai.types import Tool, ToolCall
+
+
+class ToolParamError(ValueError):
+    """Raised when a tool call's arguments fail schema validation."""
+
+
+class UnknownToolError(KeyError):
+    """Raised when a tool call targets a name absent from the tool set."""
+
+
+def find_tool(tools: list[Tool], name: str) -> Tool:
+    for t in tools:
+        if t.name == name:
+            return t
+    raise UnknownToolError(name)
+
+
+def validate_tool_call(tools: list[Tool], call: ToolCall) -> BaseModel:
+    """Validate ``call.arguments`` against the named tool's parameter model.
+
+    Returns the parsed model instance on success; raises :class:`ToolParamError` on
+    failure so the caller can surface the error message to the model.
+    """
+    tool = find_tool(tools, call.name)
+    return _parse(tool.parameters, call.arguments)
+
+
+def _parse(model_cls: type[BaseModel], arguments: dict[str, Any]) -> BaseModel:
+    try:
+        return model_cls.model_validate(arguments)
+    except ValidationError as exc:
+        # Flatten pydantic errors into a compact, model-readable message.
+        parts = []
+        for err in exc.errors():
+            loc = ".".join(str(x) for x in err["loc"]) or "<root>"
+            parts.append(f"{loc}: {err['msg']}")
+        raise ToolParamError("; ".join(parts)) from exc

minima_harness/ai/types.py

@@ -0,0 +1,204 @@
+"""Core LLM types — a lean Python port of the ``@earendil-works/pi-ai`` data model.
+
+Wire-contract discriminator values (``type`` / ``role`` / ``stopReason``) intentionally
+match PI's so anyone familiar with the TS library recognizes the shapes. Field names
+are snake-cased to stay pythonic; serialization is therefore *not* byte-compatible with
+the TS library, which is fine — this port is consumed in-process, not over the wire.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+# ---------------------------------------------------------------------------
+# Cost / usage
+# ---------------------------------------------------------------------------
+
+
+class Cost(BaseModel):
+    """USD cost breakdown for a single generation.
+
+    ``input``/``output`` are the uncached token costs; ``cache_read``/``cache_write`` are
+    the prompt-cache components (read ~0.1x input, write ~1.25x input on Anthropic).
+    ``total`` is the true realized spend across all four — this is what flows to Minima's
+    ``actual_cost_usd`` so the observed cost tier reflects real post-cache economics.
+    """
+
+    input: float = 0.0
+    output: float = 0.0
+    cache_read: float = 0.0
+    cache_write: float = 0.0
+    total: float = 0.0
+
+
+class Usage(BaseModel):
+    """Token accounting; mirrors PI's ``AssistantMessage.usage``."""
+
+    input: int = 0
+    output: int = 0
+    cache_read: int = 0
+    cache_write: int = 0
+    cost: Cost = Field(default_factory=Cost)
+
+
+# ---------------------------------------------------------------------------
+# Modalities & model descriptor
+# ---------------------------------------------------------------------------
+
+
+class Modality(StrEnum):
+    text = "text"
+    image = "image"
+
+
+# API ids match PI's registry so provider dispatch is recognizable.
+ApiId = Literal[
+    "anthropic-messages",
+    "google-generative-ai",
+    "openai-completions",
+    "faux",
+]
+
+
+@dataclass(slots=True)
+class ModelCost:
+    """Per-million-token USD prices."""
+
+    input: float
+    output: float
+    cache_read: float = 0.0
+    cache_write: float = 0.0
+
+
+@dataclass(slots=True)
+class Model:
+    """A callable model. Custom/OpenAI-compatible endpoints set ``base_url``."""
+
+    id: str
+    provider: str
+    api: ApiId
+    name: str
+    cost: ModelCost
+    context_window: int
+    max_tokens: int
+    input: tuple[Modality, ...] = (Modality.text,)
+    reasoning: bool = False
+    base_url: str | None = None
+    headers: dict[str, str] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Content blocks
+# ---------------------------------------------------------------------------
+
+
+class TextContent(BaseModel):
+    type: Literal["text"] = "text"
+    text: str
+
+
+class ImageContent(BaseModel):
+    type: Literal["image"] = "image"
+    data: str  # base64-encoded
+    mime_type: str = "image/png"
+
+
+class ThinkingContent(BaseModel):
+    type: Literal["thinking"] = "thinking"
+    thinking: str
+    # Anthropic signs every thinking block; the signature MUST be echoed back verbatim when the
+    # block is replayed in history (incl. within a tool-use turn), or the API 400s with
+    # "thinking.signature: Field required". Empty for providers that don't sign (e.g. Gemini).
+    signature: str = ""
+
+
+class ToolCall(BaseModel):
+    type: Literal["toolCall"] = "toolCall"
+    id: str
+    name: str
+    # May be partial during streaming; defaults to ``{}``, never None (matches PI).
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+ContentBlock = Annotated[
+    TextContent | ImageContent | ThinkingContent | ToolCall,
+    Field(discriminator="type"),
+]
+
+# ---------------------------------------------------------------------------
+# Messages
+# ---------------------------------------------------------------------------
+
+Role = Literal["user", "assistant", "toolResult"]
+StopReason = Literal["stop", "length", "toolUse", "error", "aborted"]
+
+
+class Message(BaseModel):
+    """A conversation message. ``content`` may be a bare string for convenience."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    role: Role
+    content: list[ContentBlock]
+    timestamp: int | None = None
+    # toolResult-only fields:
+    tool_call_id: str | None = None
+    tool_name: str | None = None
+    is_error: bool = False
+
+    @field_validator("content", mode="before")
+    @classmethod
+    def _coerce_content(cls, value: object) -> object:
+        if isinstance(value, str):
+            return [TextContent(text=value)]
+        return value
+
+    @property
+    def text(self) -> str:
+        """Concatenated text across all TextContent blocks (empty for non-text)."""
+        return "".join(b.text for b in self.content if isinstance(b, TextContent))
+
+
+class AssistantMessage(Message):
+    """An assistant turn. Carries usage, stop reason, and optional error info."""
+
+    role: Literal["assistant"] = "assistant"
+    model: str = ""
+    stop_reason: StopReason = "stop"
+    usage: Usage = Field(default_factory=Usage)
+    error_message: str | None = None
+    response_id: str | None = None
+
+    @property
+    def tool_calls(self) -> list[ToolCall]:
+        if isinstance(self.content, str):
+            return []
+        return [b for b in self.content if isinstance(b, ToolCall)]
+
+
+# ---------------------------------------------------------------------------
+# Tools (declared here to avoid an import cycle — logic lives in tools.py)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class Tool:
+    """A callable tool. ``parameters`` is a pydantic model class (the TypeBox analogue)."""
+
+    name: str
+    description: str
+    parameters: type[BaseModel]
+
+
+class Context(BaseModel):
+    """A serializable conversation context (system prompt + messages + tools)."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    system_prompt: str | None = None
+    messages: list[Message] = Field(default_factory=list)
+    tools: list[Tool] = Field(default_factory=list)

minima_harness/ai/usage.py

@@ -0,0 +1,41 @@
+"""Cost computation: realized tokens x per-model prices -> USD.
+
+Feeds Minima's ``actual_cost_usd`` feedback field. Keeping the realized-cost basis in
+the harness (rather than echoing Minima's *prior* ``est_cost_usd``) lets Minima climb
+estimate -> observed -> rescaled, which is its single biggest accuracy lever.
+"""
+
+from __future__ import annotations
+
+from minima_harness.ai.types import Cost, Model, Usage
+
+# Registry prices are per-million tokens; divide token counts by 1e6.
+_PER_MTOK = 1_000_000.0
+
+
+def cost_for(model: Model, usage: Usage) -> Cost:
+    """Compute the true USD cost of ``usage`` against ``model``'s price table.
+
+    Cache reads/writes ARE folded into ``total`` (read ~0.1x, write ~1.25x the input
+    rate). Anthropic reports ``input`` as the *uncached* portion only, so omitting the
+    cache components understated realized cost; including them is what lets the cost meter
+    show genuine savings and lets Minima's observed tier learn real post-cache economics.
+    """
+    in_usd = usage.input * model.cost.input / _PER_MTOK
+    out_usd = usage.output * model.cost.output / _PER_MTOK
+    cache_read_usd = usage.cache_read * model.cost.cache_read / _PER_MTOK
+    cache_write_usd = usage.cache_write * model.cost.cache_write / _PER_MTOK
+    total = in_usd + out_usd + cache_read_usd + cache_write_usd
+    return Cost(
+        input=in_usd,
+        output=out_usd,
+        cache_read=cache_read_usd,
+        cache_write=cache_write_usd,
+        total=total,
+    )
+
+
+def attach_cost(model: Model, usage: Usage) -> Usage:
+    """Return ``usage`` with its ``cost`` field populated for ``model``."""
+    usage.cost = cost_for(model, usage)
+    return usage

minima_harness/minima/__init__.py

@@ -0,0 +1,40 @@
+"""minima_harness.minima — the routing/judging integration layer.
+
+Wires the ported agent runtime to Minima: each ``MinimaAgent.prompt`` recommends a model,
+runs the turn, judges quality, and feeds the realized tokens/cost/latency back so Minima's
+memory sharpens (recommend -> run -> judge -> feedback).
+"""
+
+from minima_harness.minima.config import DEFAULT_CANDIDATES, HarnessConfig
+from minima_harness.minima.judge import (
+    ConstJudge,
+    DeterministicJudge,
+    LLMJudge,
+    QualityJudge,
+)
+from minima_harness.minima.mapping import ModelMapping
+from minima_harness.minima.meter import CostMeter, CostRow, CostTotals
+from minima_harness.minima.router import MinimaRouter, Ranking, RoutingResult
+from minima_harness.minima.runtime import BeforeRoute, MinimaAgent
+from minima_harness.minima.signals import CodeHealthExtractor, ContextExtractor, SignalBundle
+
+__all__ = [
+    "BeforeRoute",
+    "CodeHealthExtractor",
+    "ConstJudge",
+    "ContextExtractor",
+    "DEFAULT_CANDIDATES",
+    "CostMeter",
+    "CostRow",
+    "CostTotals",
+    "DeterministicJudge",
+    "HarnessConfig",
+    "LLMJudge",
+    "MinimaAgent",
+    "MinimaRouter",
+    "ModelMapping",
+    "QualityJudge",
+    "Ranking",
+    "RoutingResult",
+    "SignalBundle",
+]

minima_harness/minima/cache.py

@@ -0,0 +1,102 @@
+"""Semantic response cache — a free 'recommendation' when a near-duplicate prompt repeats.
+
+A cache HIT returns a prior response with ZERO LLM cost (and ~no latency). Similarity
+defaults to a cheap, dependency-free normalized-token Jaccard, which catches exact and
+near-duplicate coding prompts (the realistic hit case for a coding agent); inject
+``similarity_fn`` (e.g. embedding cosine via Mubit's ANN) for true semantic matching.
+Bounded LRU with an optional TTL. Disabled by default at the call site
+(``HarnessConfig.cache_enabled``); a too-loose threshold risks stale hits, so it ships off.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import OrderedDict
+from collections.abc import Callable
+from dataclasses import dataclass
+
+_WORD = re.compile(r"[a-z0-9_]+")
+
+
+def _tokens(text: str) -> set[str]:
+    return set(_WORD.findall(text.lower()))
+
+
+def jaccard(a: str, b: str) -> float:
+    """Token-set Jaccard similarity in [0, 1] (cheap, dependency-free, paraphrase-blind)."""
+    ta, tb = _tokens(a), _tokens(b)
+    if not ta and not tb:
+        return 1.0
+    if not ta or not tb:
+        return 0.0
+    return len(ta & tb) / len(ta | tb)
+
+
+@dataclass(slots=True)
+class CacheHit:
+    response: str
+    similarity: float
+    prompt: str
+
+
+SimilarityFn = Callable[[str, str], float]
+
+
+class SemanticCache:
+    """Bounded prompt->response cache keyed by similarity. ``get`` returns the best stored
+    response whose similarity clears ``threshold`` (or None)."""
+
+    def __init__(
+        self,
+        *,
+        threshold: float = 0.95,
+        max_entries: int = 512,
+        similarity_fn: SimilarityFn | None = None,
+        now_fn: Callable[[], float] | None = None,
+        ttl_s: float | None = None,
+    ) -> None:
+        self.threshold = threshold
+        self.max_entries = max_entries
+        self._sim = similarity_fn or jaccard
+        self._now = now_fn
+        self._ttl = ttl_s
+        self._store: OrderedDict[str, tuple[str, float]] = OrderedDict()
+        self.hits = 0
+        self.misses = 0
+
+    def get(self, prompt: str) -> CacheHit | None:
+        self._expire()
+        best_prompt: str | None = None
+        best_resp = ""
+        best_sim = 0.0
+        for p, (resp, _ts) in self._store.items():
+            sim = self._sim(prompt, p)
+            if sim > best_sim:
+                best_sim, best_prompt, best_resp = sim, p, resp
+        if best_prompt is not None and best_sim >= self.threshold:
+            self.hits += 1
+            self._store.move_to_end(best_prompt)
+            return CacheHit(response=best_resp, similarity=best_sim, prompt=best_prompt)
+        self.misses += 1
+        return None
+
+    def put(self, prompt: str, response: str) -> None:
+        if not response:
+            return
+        ts = self._now() if self._now is not None else 0.0
+        self._store[prompt] = (response, ts)
+        self._store.move_to_end(prompt)
+        while len(self._store) > self.max_entries:
+            self._store.popitem(last=False)
+
+    def _expire(self) -> None:
+        if self._ttl is None or self._now is None:
+            return
+        cutoff = self._now() - self._ttl
+        for p in [p for p, (_r, ts) in self._store.items() if ts < cutoff]:
+            self._store.pop(p, None)
+
+    @property
+    def hit_rate(self) -> float:
+        total = self.hits + self.misses
+        return self.hits / total if total else 0.0

minima_harness/minima/config.py

@@ -0,0 +1,85 @@
+"""Harness configuration: where Minima lives, the candidate pool, and judge policy.
+
+Defaults target the **hosted** Minima (``https://api.minima.sh``) so a freshly installed
+``minima`` works out of the box — set ``MUBIT_API_KEY`` (routing auth) and a provider key
+and routing just works. For local development against ``make run`` on :8080, set
+``MINIMA_URL=http://localhost:8080`` (the repo's ``.env.harness`` does this explicitly).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+# The hosted service is the product default. Local dev sets MINIMA_URL explicitly.
+DEFAULT_MINIMA_URL = "https://api.minima.sh"
+DEFAULT_JUDGE_MODEL = "claude-haiku-4-5"
+
+# Candidate set mirrors examples/agent_warmup.py so cold-start routing behaves the same.
+DEFAULT_CANDIDATES: list[str] = [
+    "gemini-2.5-flash",
+    "claude-haiku-4-5",
+    "claude-sonnet-4-6",
+    "gemini-2.5-pro",
+    "claude-opus-4-8",
+]
+
+
+@dataclass(slots=True)
+class HarnessConfig:
+    """Routing + judging policy for a :class:`MinimaAgent` run."""
+
+    minima_url: str = DEFAULT_MINIMA_URL
+    minima_api_key: str | None = None
+    # Model ids Minima is allowed to pick from (-> Constraints.candidate_models).
+    candidates: list[str] = field(default_factory=lambda: list(DEFAULT_CANDIDATES))
+    # True when the user explicitly pinned a single model via /model: routing is bypassed and
+    # that model (candidates[0]) runs directly. Distinct from "candidates happens to be length
+    # 1" (which can occur from key-gating) — only an explicit pin skips Minima.
+    pinned: bool = False
+    # Memory isolation lane (-> namespace). None = default lane.
+    namespace: str | None = None
+    # cost/quality slider: 0=cheapest acceptable, 10=highest quality.
+    cost_quality_tradeoff: float = 5.0
+    # Independent grader model (different provider avoids self-grading bias).
+    judge_model: str = DEFAULT_JUDGE_MODEL
+    # Judge every Nth terminal turn (1 = every turn). 0 disables judging.
+    judge_every: int = 1
+    baseline_model_id: str | None = None
+    # Minima HTTP timeout (s). Cold-start recommend can take >10s when Minima consults its
+    # LLM reasoner (thin evidence), so a tight timeout silently degrades to OFFLINE routing.
+    # 30s comfortably covers reasoner + recall. Override with MINIMA_TIMEOUT.
+    timeout: float = 30.0
+    # When True, an unreachable Minima falls back to a fixed default model instead of
+    # raising. Keeps ad-hoc runs working without a Minima instance.
+    allow_offline: bool = True
+    # Semantic response cache (/cache): a near-duplicate prompt returns a prior answer for
+    # free. Off by default — a too-loose threshold risks stale hits, and coding prompts are
+    # mostly unique. threshold is the min similarity for a hit.
+    cache_enabled: bool = False
+    cache_threshold: float = 0.95
+
+    @classmethod
+    def from_env(cls, **overrides: object) -> HarnessConfig:
+        cfg = cls()
+        cfg.refresh_routing_env()
+        timeout_env = os.environ.get("MINIMA_TIMEOUT")
+        if timeout_env:
+            try:
+                cfg.timeout = float(timeout_env)
+            except ValueError:
+                pass
+        for key, value in overrides.items():
+            setattr(cfg, key, value)
+        return cfg
+
+    def refresh_routing_env(self) -> None:
+        """Re-read just the Minima endpoint + routing auth from the environment, in place.
+
+        Used when a key/URL is set via the ``/config`` overlay mid-session: those land in
+        ``os.environ`` but this dataclass (and the live Minima client built from it) were
+        captured at startup. Refreshing here lets ``/reconnect`` rebuild a working client
+        without a restart. Leaves the candidate pool, namespace, judge policy, etc. untouched.
+        """
+        self.minima_url = os.environ.get("MINIMA_URL", self.minima_url)
+        self.minima_api_key = os.environ.get("MINIMA_API_KEY") or os.environ.get("MUBIT_API_KEY")