puremethod 0.1.0__py3-none-any.whl

llm/prices.py

@@ -0,0 +1,98 @@
+"""Versioned price table (07-llm.md §4) and cost arithmetic.
+
+Prices are USD per million tokens. A model with no entry is refused (INV-3). A local model
+needs an explicit entry, which may be 0.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any
+
+from .types import PriceUnknown, Usage
+
+
+@dataclass(frozen=True)
+class ModelPrice:
+    input: float
+    output: float
+    cache_read: float | None = None   # None: charged at the input price (upper bound)
+    cache_write: float | None = None  # None: charged at the input price
+    # Optional long-context tier: when input tokens exceed the threshold, the whole request
+    # is charged at these prices.
+    long_threshold: int | None = None
+    long_input: float | None = None
+    long_output: float | None = None
+    # A self-hosted model whose cost is not known per token (billed by the hour, or not
+    # known): calls count 0 against the money limit, are recorded `metered: false`, and need
+    # the run's unmetered-compute consent (INV-3, KB-036). Its input and output are 0.
+    unmetered: bool = False
+
+    @staticmethod
+    def unmetered_price() -> ModelPrice:
+        return ModelPrice(0.0, 0.0, unmetered=True)
+
+    def tier(self, input_tokens: int) -> ModelPrice:
+        if self.long_threshold is not None and input_tokens > self.long_threshold:
+            return replace(self, input=self.long_input or self.input,
+                           output=self.long_output or self.output, long_threshold=None)
+        return self
+
+
+@dataclass(frozen=True)
+class PriceTable:
+    version: str
+    source: str
+    prices: dict[tuple[str, str], ModelPrice]  # (provider, model) -> price
+
+    def get(self, provider: str, model: str) -> ModelPrice:
+        price = self.prices.get((provider, model))
+        if price is None:
+            raise PriceUnknown(f"no price for {provider}/{model}; add one to the run config")
+        return price
+
+    def with_overrides(self, overrides: dict[str, dict[str, Any]]) -> PriceTable:
+        """Overrides keyed `provider/model`, values are ModelPrice fields."""
+        prices = dict(self.prices)
+        for key, fields in overrides.items():
+            provider, _, model = key.partition("/")
+            if not model:
+                raise ValueError(f"price override key {key!r} must be provider/model")
+            prices[(provider, model)] = ModelPrice(**fields)
+        version = f"{self.version}+overrides" if overrides else self.version
+        return PriceTable(version=version, source=self.source, prices=prices)
+
+
+def cost_usd(price: ModelPrice, usage: Usage) -> float:
+    p = price.tier(usage.input_tokens + usage.cache_read_tokens + usage.cache_write_tokens)
+    cache_read = p.cache_read if p.cache_read is not None else p.input
+    cache_write = p.cache_write if p.cache_write is not None else p.input
+    return (usage.input_tokens * p.input + usage.output_tokens * p.output
+            + usage.cache_read_tokens * cache_read
+            + usage.cache_write_tokens * cache_write) / 1_000_000
+
+
+def bound_usd(price: ModelPrice, input_tokens: int, max_tokens: int) -> float:
+    """Upper bound for one call: every input token at the highest input-side price."""
+    p = price.tier(input_tokens)
+    input_side = max(p.input, p.cache_read or 0.0, p.cache_write or 0.0)
+    return (input_tokens * input_side + max_tokens * p.output) / 1_000_000
+
+
+# Source: Anthropic first-party API list prices for current models, as given in the
+# claude-api reference (model table cached 2026-10-06), read 2026-10-27. Cache writes at
+# 1.25x input (5-minute TTL). Claude Haiku 5.5: listed prices apply up to 100K prompt
+# tokens; above that, $0.50 / $2.50. No OpenAI prices are shipped: they were not checked
+# against a current source, so OpenAI models need a price in the run config (INV-3).
+DEFAULT_PRICES = PriceTable(
+    version="2026-10-27.1",
+    source="Anthropic list prices via the claude-api reference, cached 2026-10-06",
+    prices={
+        ("anthropic", "claude-fable-5-1"): ModelPrice(10.00, 50.00, 0.25, 12.50),
+        ("anthropic", "claude-opus-5-5"): ModelPrice(4.00, 20.00, 0.20, 5.00),
+        ("anthropic", "claude-sonnet-5-5"): ModelPrice(2.00, 10.00, 0.20, 2.50),
+        ("anthropic", "claude-haiku-5-5"): ModelPrice(0.10, 0.50, None, 0.125,
+                                                       long_threshold=100_000,
+                                                       long_input=0.50, long_output=2.50),
+    },
+)

llm/tokens.py

@@ -0,0 +1,18 @@
+"""Fallback token estimate (07-llm.md §5 step 2)."""
+
+from __future__ import annotations
+
+import math
+
+# Per-message allowance for role markers and framing, on top of the content estimate.
+MESSAGE_OVERHEAD = 8
+REQUEST_OVERHEAD = 16
+
+
+def estimate_tokens(text: str) -> int:
+    """4 tokens per 3 characters, plus 10%, rounded up."""
+    return math.ceil(len(text) * 4 / 3 * 1.1)
+
+
+def estimate_request(texts: list[str]) -> int:
+    return sum(estimate_tokens(t) + MESSAGE_OVERHEAD for t in texts) + REQUEST_OVERHEAD

llm/types.py

@@ -0,0 +1,106 @@
+"""Messages, results, call records and errors (07-llm.md §3)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, TypedDict
+
+Role = Literal["planner", "coder", "analyst", "writer"]
+ROLES: tuple[Role, ...] = ("planner", "coder", "analyst", "writer")
+
+
+class Message(TypedDict):
+    role: Literal["system", "user", "assistant"]
+    content: str
+
+
+@dataclass(frozen=True)
+class Usage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+
+
+@dataclass
+class CallRecord:
+    """One provider call, successful or not (INV-1). Same shape as the adapters' records.
+
+    `request` and `response` hold the full text for `loop` to store as ledger artifacts.
+    """
+
+    source: str
+    role: str
+    provider: str
+    model: str
+    model_reported: str | None
+    fallback: bool
+    attempt: int
+    parameters: dict[str, Any]
+    started_at: str
+    ended_at: str
+    status: Literal["ok", "error"]
+    usage: Usage
+    cost_usd: float
+    price_table_version: str
+    bound_usd: float
+    bound_exceeded: bool
+    error_type: str | None
+    error_message: str | None
+    request: dict[str, Any]
+    response: str | None
+    metered: bool = True  # False for a model priced as unmetered (INV-3, KB-036)
+    model_digest: str | None = None  # as the server reports it, e.g. Ollama (§3, KB-036)
+
+    def to_dict(self) -> dict[str, Any]:
+        d = dict(self.__dict__)
+        d["usage"] = dict(self.usage.__dict__)
+        return d
+
+
+@dataclass
+class LLMResult:
+    text: str
+    parsed: Any
+    usage: Usage
+    cost_usd: float
+    model_reported: str | None
+    stop_reason: str | None
+    record: CallRecord
+    records: list[CallRecord] = field(default_factory=list)
+
+
+class LLMError(Exception):
+    """Base error. `records` holds every call made before the failure (INV-1)."""
+
+    def __init__(self, message: str, records: list[CallRecord] | None = None) -> None:
+        super().__init__(message)
+        self.records: list[CallRecord] = records or []
+
+
+class ProviderUnavailable(LLMError):
+    """Outage or persistent transient failure. The caller pauses the run (SYS-INV-7)."""
+
+
+class RateLimited(LLMError):
+    """Rate limited after the retries ran out."""
+
+
+class QuotaExhausted(LLMError):
+    """The account has no quota or credit left."""
+
+
+class AuthError(LLMError):
+    """Credentials missing, invalid, or not allowed."""
+
+
+class InvalidOutput(LLMError):
+    """The output still failed its schema after the retries."""
+
+
+class PriceUnknown(LLMError):
+    """The model has no price; it is refused rather than treated as free (INV-3)."""
+
+
+class RequestRejected(LLMError):
+    """The provider refused the request as malformed (HTTP 400, 404, 413, 422)."""

loop/__init__.py

@@ -0,0 +1,19 @@
+"""loop: the research cycle (docs/knowledge_base/03-loop.md)."""
+
+from .config import (
+    Autonomy,
+    ExecutorChoice,
+    LadderConfig,
+    Limits,
+    PaperConfig,
+    PureTraceUse,
+    RunConfig,
+    next_stage,
+    stage_budget_s,
+)
+from .core import LimitReached, Loop, RunStatus
+from .decide import RULES, Verdict, evaluate
+
+__all__ = ["RULES", "Autonomy", "ExecutorChoice", "LadderConfig", "LimitReached", "Limits",
+           "Loop", "PaperConfig", "PureTraceUse", "RunConfig", "RunStatus", "Verdict",
+           "evaluate", "next_stage", "stage_budget_s"]

loop/config.py

@@ -0,0 +1,108 @@
+"""RunConfig (03-loop.md §3): validated once, then fixed for the run (INV-6)."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+CHECKPOINTS = ("C1", "C2")
+
+
+class _Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class Limits(_Strict):
+    wall_clock: float = Field(gt=0, description="hours")
+    money: float = Field(gt=0, description="USD")
+    writing_reserve: float = Field(default=0.15, ge=0.05, le=0.5)
+
+
+class ExecutorChoice(_Strict):
+    id: str = Field(min_length=1)
+    allow_unisolated: bool = False
+
+
+class LadderConfig(_Strict):
+    pilot_minutes: float = Field(default=5.0, gt=0)
+    growth_factor: float = Field(default=3.0, gt=1)
+    max_stages: int = Field(default=3, ge=1, le=6)
+    confirmation_seeds: int = Field(default=3, ge=1, le=10)
+
+
+class PureTraceUse(_Strict):
+    screening: bool = False
+    selfcheck: bool = False
+
+
+class PaperConfig(_Strict):
+    template: Literal["article", "ieeetran"] = "article"
+    disclosure: bool = True
+
+
+class Autonomy(_Strict):
+    mode: Literal["autonomous", "checkpoint"] = "checkpoint"
+    checkpoints: tuple[str, ...] = CHECKPOINTS
+
+    @model_validator(mode="after")
+    def _known(self) -> Autonomy:
+        unknown = set(self.checkpoints) - set(CHECKPOINTS)
+        if unknown:
+            raise ValueError(f"unknown checkpoints: {sorted(unknown)}")
+        return self
+
+
+class RunConfig(_Strict):
+    idea: str = Field(min_length=1)
+    domain: Literal["ml", "simulation"]
+    autonomy: Autonomy = Autonomy()
+    limits: Limits
+    executor: ExecutorChoice
+    accept_unmetered_compute: bool = False
+    llm: dict[str, dict[str, Any]]
+    budget_ladder: LadderConfig = LadderConfig()
+    puretrace: PureTraceUse = PureTraceUse()
+    paper: PaperConfig = PaperConfig()
+    data_hints: tuple[str, ...] = ()
+    job_credentials: tuple[str, ...] = ()  # names the experiments may receive
+
+    @model_validator(mode="after")
+    def _roles(self) -> RunConfig:
+        missing = {"planner", "coder", "analyst"} - set(self.llm)
+        if missing:
+            raise ValueError(f"llm must map roles {sorted(missing)}")
+        return self
+
+    def checkpoint_on(self, cid: str) -> bool:
+        return self.autonomy.mode == "checkpoint" and cid in self.autonomy.checkpoints
+
+    def credential_names(self) -> list[str]:
+        """Every credential the run uses, so its values are registered as secrets."""
+        names = {str(r["credential"]) for r in self.llm.values() if r.get("credential")}
+        for r in self.llm.values():
+            fb = r.get("fallback")
+            if isinstance(fb, dict) and fb.get("credential"):
+                names.add(str(fb["credential"]))
+        names.update(self.job_credentials)
+        return sorted(names)
+
+
+def stage_budget_s(ladder: LadderConfig, stage: str) -> float:
+    """Stage k gets pilot × growth^k; `confirm` gets the last stage's budget; `smoke` a
+    tenth of the pilot (at least 30 s)."""
+    pilot = ladder.pilot_minutes * 60
+    if stage == "smoke":
+        return max(pilot / 10, 30.0)
+    if stage == "confirm":
+        return pilot * ladder.growth_factor ** (ladder.max_stages - 1)
+    return pilot * ladder.growth_factor ** int(stage)
+
+
+def next_stage(ladder: LadderConfig, stage: str) -> str:
+    if stage == "smoke":
+        return "0"
+    if stage == "confirm":
+        raise ValueError("confirm is the last stage")
+    k = int(stage) + 1
+    return "confirm" if k >= ladder.max_stages else str(k)