backspec 0.0.1__py3-none-any.whl

backspec/kernel/usage.py

@@ -0,0 +1,50 @@
+"""What a model call cost, and the rules for estimating it before and after.
+
+A backend may report the tokens of its last call (`last_usage()`); when it does not, the
+cost is estimated from characters. Estimates are always flagged as such.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+CHARS_PER_TOKEN = 4
+
+# Tokens reserved for a stage's reply before a call is sent, on top of the prompt's own estimate.
+# These are allowances, not limits: a reply may be longer. They bound how far a run can overshoot.
+OUTPUT_ALLOWANCE = {"observe": 3000, "orient": 1500, "assign": 3000, "synthesise": 3000,
+                    "consolidate": 3000, "assess": 2000}
+DEFAULT_OUTPUT_ALLOWANCE = 2000
+
+
+@dataclass(frozen=True)
+class Usage:
+    input_tokens: int
+    output_tokens: int
+    estimated: bool = False
+    cost_usd: float | None = None   # the backend's own figure for the call, when it gives one
+
+
+def estimate_tokens(text: str) -> int:
+    """Characters divided by four, rounded up."""
+    return (len(text) + CHARS_PER_TOKEN - 1) // CHARS_PER_TOKEN
+
+
+def estimate_usage(prompt: str, reply: str) -> Usage:
+    return Usage(estimate_tokens(prompt), estimate_tokens(reply), estimated=True)
+
+
+def reservation(stage: str, prompt: str) -> int:
+    """What a call is expected to cost, held against the budget until it returns."""
+    return estimate_tokens(prompt) + OUTPUT_ALLOWANCE.get(stage, DEFAULT_OUTPUT_ALLOWANCE)
+
+
+@dataclass
+class Spend:
+    """A snapshot of what a run has used so far. Cached replies count as calls to their stage's
+    `cached`, never as tokens."""
+    input_tokens: int = 0
+    output_tokens: int = 0
+    estimated: bool = False
+    cost_usd: float | None = None
+    budget_reached: bool = False
+    by_stage: dict[str, dict[str, int]] = field(default_factory=dict)   # stage -> calls, cached, input_tokens, output_tokens

backspec/modules/capabilities/domain.py

@@ -0,0 +1,108 @@
+"""Capabilities: feature areas as a user would name them, and which observations belong to each.
+
+Grouping is by observation, not by file: one large file often feeds several capabilities.
+"""
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, Field
+
+PLUMBING = "plumbing"
+UNASSIGNED = "unassigned"
+ID_PATTERN = re.compile(r"[a-z0-9_]+")
+
+
+class CapabilitiesFileError(ValueError):
+    """The capabilities file is unusable. The message names the file and every problem."""
+
+
+class Capability(BaseModel):
+    id: str
+    name: str
+    summary: str = ""
+    includes: list[str] = Field(default_factory=list)
+
+
+class OrientReply(BaseModel):
+    capabilities: list[Capability]
+
+
+class AssignReply(BaseModel):
+    assignments: dict[str, str]
+
+
+def listing(observations: list[tuple[str, str, str]]) -> str:
+    """Observations as `id | statement` lines under a `## path` header per file.
+    Each item is (id, path, statement)."""
+    out: list[str] = []
+    current = None
+    for obs_id, path, statement in observations:
+        if path != current:
+            out.append(f"## {path}")
+            current = path
+        out.append(f"{obs_id} | {statement}")
+    return "\n".join(out)
+
+
+def thin(items: list, limit: int) -> list:
+    """At most `limit` items, taken evenly across the list, so that every file is represented."""
+    if len(items) <= limit:
+        return items
+    step = len(items) / limit
+    return [items[int(index * step)] for index in range(limit)]
+
+
+def _text(value: object) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def parse_capabilities(data: object, source: str) -> list[Capability]:
+    """Turn what was read from a capabilities file into capabilities, or refuse it.
+
+    Every problem is collected, so the owner can fix the file in one pass. `plumbing` is added
+    when the file lacks it."""
+    problems: list[str] = []
+    if isinstance(data, dict) and isinstance(data.get("capabilities"), list):
+        data = data["capabilities"]
+    if not isinstance(data, list):
+        raise CapabilitiesFileError(f"{source}: expected a list of capabilities (or a `capabilities:` key holding one)")
+    found: list[Capability] = []
+    seen: set[str] = set()
+    for position, entry in enumerate(data, start=1):
+        label = f"entry {position}"
+        if not isinstance(entry, dict):
+            problems.append(f"{label}: expected a mapping with id, name, summary and includes")
+            continue
+        cap_id = entry.get("id")
+        if isinstance(cap_id, str) and cap_id:
+            label = f"entry {position} ({cap_id})"
+        if not isinstance(cap_id, str) or not ID_PATTERN.fullmatch(cap_id):
+            problems.append(f"{label}: id must be lowercase letters, digits and underscores, got {cap_id!r}")
+        elif cap_id in seen:
+            problems.append(f"{label}: id {cap_id!r} is used more than once")
+        else:
+            seen.add(cap_id)
+        if not _text(entry.get("name")):
+            problems.append(f"{label}: name must not be empty")
+        summary, includes = entry.get("summary", ""), entry.get("includes", [])
+        if summary is None:
+            summary = ""
+        if not isinstance(summary, str):
+            problems.append(f"{label}: summary must be text")
+        if includes is None:
+            includes = []
+        if not isinstance(includes, list) or not all(isinstance(item, str) for item in includes):
+            problems.append(f"{label}: includes must be a list of text")
+        if not problems:
+            found.append(Capability(id=cap_id, name=entry["name"].strip(), summary=summary.strip(), includes=includes))
+    if problems:
+        raise CapabilitiesFileError(f"{source} is not usable:\n" + "\n".join(f"  - {p}" for p in problems))
+    return with_plumbing(found)
+
+
+def with_plumbing(capabilities: list[Capability]) -> list[Capability]:
+    if any(c.id == PLUMBING for c in capabilities):
+        return list(capabilities)
+    return [*capabilities, Capability(id=PLUMBING, name="Internal mechanics",
+                                      summary="Machinery no user or operator would notice.")]

backspec/modules/capabilities/facade.py

@@ -0,0 +1,48 @@
+"""Capabilities, as the rest of backspec sees it."""
+from __future__ import annotations
+
+from backspec.kernel.llm import LLMPort
+from backspec.modules.capabilities.domain import PLUMBING, UNASSIGNED, CapabilitiesFileError, Capability
+from backspec.modules.capabilities.ports import CapabilitiesStorePort
+from backspec.modules.capabilities.use_cases import assign, load, orient
+from backspec.modules.evidence.facade import Observation
+
+__all__ = ["PLUMBING", "UNASSIGNED", "CapabilitiesFacade", "CapabilitiesFileError", "CapabilitiesStorePort",
+           "Capability"]
+
+
+class CapabilitiesFacade:
+    def __init__(self, llm: LLMPort, workers: int = 4, store: CapabilitiesStorePort | None = None):
+        self._llm = llm
+        self._workers = workers
+        self._store = store
+
+    @property
+    def location(self) -> str:
+        return self._store.location if self._store else ""
+
+    def load(self) -> list[Capability] | None:
+        """The capabilities file's list (with `plumbing`), None if there is no file. Raises
+        `CapabilitiesFileError` naming every problem in a file that breaks the rules."""
+        return load(self._store) if self._store else None
+
+    def exists(self) -> bool:
+        """Whether there is a file at all, usable or not."""
+        if self._store is None:
+            return False
+        try:
+            return self._store.read() is not None
+        except CapabilitiesFileError:
+            return True
+
+    def save(self, capabilities: list[Capability]) -> None:
+        if self._store is None:
+            raise ValueError("no capabilities file is configured")
+        self._store.write(capabilities)
+
+    def orient(self, observations: list[Observation]) -> list[Capability]:
+        return orient(observations, self._llm)
+
+    def assign(self, observations: list[Observation], capabilities: list[Capability],
+               earlier: dict[str, str] | None = None) -> dict[str, str]:
+        return assign(observations, capabilities, self._llm, self._workers, earlier)

backspec/modules/capabilities/ports.py

@@ -0,0 +1,21 @@
+"""What capabilities needs from the outside world: somewhere to keep the owner's capability list."""
+from __future__ import annotations
+
+from typing import Protocol
+
+from backspec.modules.capabilities.domain import Capability
+
+
+class CapabilitiesStorePort(Protocol):
+    @property
+    def location(self) -> str:
+        """Where the list lives, for messages."""
+        ...
+
+    def read(self) -> object | None:
+        """The parsed content of the stored list, or None when nothing is stored there.
+        Content that cannot be parsed at all raises `CapabilitiesFileError`."""
+        ...
+
+    def write(self, capabilities: list[Capability]) -> None:
+        ...

backspec/modules/capabilities/use_cases.py

@@ -0,0 +1,63 @@
+"""Orient: propose capabilities from the observations. Assign: place every observation in one."""
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+
+from backspec.kernel import prompts
+from backspec.kernel.llm import LLMError, LLMPort, LLMRequest, ask
+from backspec.modules.capabilities.domain import (UNASSIGNED, AssignReply, Capability, OrientReply, listing,
+                                              parse_capabilities, thin, with_plumbing)
+from backspec.modules.capabilities.ports import CapabilitiesStorePort
+from backspec.modules.evidence.facade import Observation
+
+ORIENT_LIMIT = 2000   # observation lines one orient call is shown
+ASSIGN_CHUNK = 280
+
+
+def _items(observations: list[Observation]) -> list[tuple[str, str, str]]:
+    ordered = sorted(observations, key=lambda o: (o.path, o.lines[0]))
+    return [(o.id, o.path, o.statement) for o in ordered]
+
+
+def orient(observations: list[Observation], llm: LLMPort) -> list[Capability]:
+    shown = listing(thin(_items(observations), ORIENT_LIMIT))
+    reply = ask(llm, LLMRequest("orient", f"{prompts.load('orient')}\n\n# The observations\n\n{shown}", "fast"), OrientReply)
+    return with_plumbing(list({c.id: c for c in reply.capabilities}.values()))
+
+
+def load(store: CapabilitiesStorePort) -> list[Capability] | None:
+    """The owner's capability list, validated, or None when there is none. Refuses a bad file."""
+    data = store.read()
+    return None if data is None else parse_capabilities(data, store.location)
+
+
+def assign(observations: list[Observation], capabilities: list[Capability], llm: LLMPort,
+           workers: int = 4, earlier: dict[str, str] | None = None) -> dict[str, str]:
+    """Observation id -> capability id. An observation the model skipped, or sent to a capability
+    that does not exist, is `unassigned`: it is still reported, never dropped.
+
+    An observation an earlier run placed in a capability that still exists stays there; only
+    the others are put to the model."""
+    known = {c.id for c in capabilities}
+    kept = {o.id: earlier[o.id] for o in observations
+            if earlier and earlier.get(o.id) in known and earlier[o.id] != UNASSIGNED}
+    everything, observations = observations, [o for o in observations if o.id not in kept]
+    described = "\n".join(f"- {c.id}: {c.name}. {c.summary} Includes: {'; '.join(c.includes)}" for c in capabilities)
+    items = _items(observations)
+    chunks = [items[start:start + ASSIGN_CHUNK] for start in range(0, len(items), ASSIGN_CHUNK)]
+    instructions = prompts.load("assign")
+
+    def run(chunk: list[tuple[str, str, str]]) -> dict[str, str]:
+        prompt = f"{instructions}\n\n# The capabilities\n\n{described}\n\n# The observations\n\n{listing(chunk)}"
+        try:
+            return ask(llm, LLMRequest("assign", prompt, "fast"), AssignReply).assignments
+        except LLMError:
+            return {}
+
+    with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+        replies = list(pool.map(run, chunks))
+    placed: dict[str, str] = {}
+    for reply in replies:
+        placed.update(reply)
+    placed.update(kept)
+    return {o.id: placed[o.id] if placed.get(o.id) in known else UNASSIGNED for o in everything}

backspec/modules/discovery/domain.py

@@ -0,0 +1,87 @@
+"""Which files are read, and why the others are not. Every file ends in exactly one state."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Literal
+
+import pathspec
+
+from backspec.kernel.text import sha256
+
+DEFAULT_EXCLUDES = [
+    ".git/", "node_modules/", ".venv/", "venv/", "vendor/", "dist/", "build/", "__pycache__/",
+    "*.lock", "package-lock.json", "*.min.js", "*.map", ".env*", "*.pem", "*.key",
+    "*.png", "*.jpg", "*.jpeg", "*.gif", "*.ico", "*.pdf", "*.woff", "*.woff2", "*.zip",
+    "/backspec.capabilities.yaml", "/backspec.review.yaml",   # backspec's own files are never read as source
+]
+MAX_BYTES = 1_000_000
+GENERATED_MARKERS = ("DO NOT EDIT", "@generated", "Code generated by")
+
+Reason = Literal["default_exclude", "not_included", "exclude_pattern",
+                 "binary", "too_large", "not_utf8", "generated"]
+
+
+@dataclass(frozen=True)
+class SourceFile:
+    """A file as it was when the run started. Every later stage reads this, never the disk."""
+    path: str
+    text: str
+    source_hash: str
+
+    @property
+    def lines(self) -> list[str]:
+        return self.text.split("\n")
+
+
+@dataclass(frozen=True)
+class Left:
+    """A file that was not read, with the state it ended in and why."""
+    path: str
+    state: Literal["excluded", "skipped"]
+    reason: Reason
+
+
+@dataclass(frozen=True)
+class Discovery:
+    files: tuple[SourceFile, ...]
+    left: tuple[Left, ...]
+
+
+@lru_cache(maxsize=64)
+def _compiled(patterns: tuple[str, ...]) -> pathspec.PathSpec:
+    try:
+        return pathspec.PathSpec.from_lines("gitignore", patterns)
+    except (KeyError, LookupError):   # older pathspec knows the syntax by its former name
+        return pathspec.PathSpec.from_lines("gitwildmatch", patterns)
+
+
+def _spec(patterns: list[str]) -> pathspec.PathSpec:
+    return _compiled(tuple(patterns))
+
+
+def excluded_by_pattern(path: str, include: list[str], exclude: list[str],
+                        default_excludes: bool = True) -> Reason | None:
+    """Why a path is out by pattern, or None. Layers only remove: exclude wins over include."""
+    if default_excludes and _spec(DEFAULT_EXCLUDES).match_file(path):
+        return "default_exclude"
+    if include and not _spec(include).match_file(path):
+        return "not_included"
+    if exclude and _spec(exclude).match_file(path):
+        return "exclude_pattern"
+    return None
+
+
+def read_or_skip(path: str, data: bytes) -> SourceFile | Left:
+    """A file's snapshot, or the reason it cannot be read as source."""
+    if len(data) > MAX_BYTES:
+        return Left(path, "skipped", "too_large")
+    if b"\x00" in data[:8192]:
+        return Left(path, "skipped", "binary")
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError:
+        return Left(path, "skipped", "not_utf8")
+    if any(marker in text[:600] for marker in GENERATED_MARKERS):
+        return Left(path, "skipped", "generated")
+    return SourceFile(path, text, sha256(text))

backspec/modules/discovery/facade.py

@@ -0,0 +1,16 @@
+"""Discovery, as the rest of backspec sees it."""
+from __future__ import annotations
+
+from backspec.modules.discovery.domain import Discovery, Left, SourceFile
+from backspec.modules.discovery.ports import RepoPort
+from backspec.modules.discovery.use_cases import discover
+
+__all__ = ["Discovery", "DiscoveryFacade", "Left", "RepoPort", "SourceFile"]
+
+
+class DiscoveryFacade:
+    def __init__(self, repo: RepoPort):
+        self._repo = repo
+
+    def discover(self, include: list[str], exclude: list[str], default_excludes: bool = True) -> Discovery:
+        return discover(self._repo, include, exclude, default_excludes)

backspec/modules/discovery/ports.py

@@ -0,0 +1,14 @@
+"""What discovery needs from the outside world."""
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class RepoPort(Protocol):
+    def list_paths(self) -> list[str]:
+        """Every candidate file under the root, relative, with forward slashes, sorted.
+        Files that version control ignores are already left out."""
+        ...
+
+    def read(self, path: str) -> bytes:
+        ...

backspec/modules/discovery/use_cases.py

@@ -0,0 +1,19 @@
+"""Walk the repository once and take a snapshot of every file that will be read."""
+from __future__ import annotations
+
+from backspec.modules.discovery.domain import Discovery, Left, SourceFile, excluded_by_pattern, read_or_skip
+from backspec.modules.discovery.ports import RepoPort
+
+
+def discover(repo: RepoPort, include: list[str], exclude: list[str],
+             default_excludes: bool = True) -> Discovery:
+    files: list[SourceFile] = []
+    left: list[Left] = []
+    for path in repo.list_paths():
+        reason = excluded_by_pattern(path, include, exclude, default_excludes)
+        if reason:
+            left.append(Left(path, "excluded", reason))
+            continue
+        outcome = read_or_skip(path, repo.read(path))
+        (files if isinstance(outcome, SourceFile) else left).append(outcome)  # type: ignore[arg-type]
+    return Discovery(tuple(files), tuple(left))